About Mac Scripting 


Scripting allows you to automate complex, repetitive, and time-consuming tasks by writing scripts that interact 
with apps, processes, and the operating system. A script consists of a series of statements, each of which 
performs a specific operation. These statements work together to automate tasks. Through scripting, you can 
create powerful workflow solutions that enhance productivity, reduce errors, save time, and save money. 


There are many different scripting languages. On the Mac, the primary ones used for automation are 
AppleScript and JavaScript. 


NOTE 


OS X also includes Automator, an app for building workflows that run prebuilt, configurable actions to perform 
tasks in apps and throughout the operating system. Automator doesn’t require you to write any code, but can 
be extended through scripting. Because Automator uses preconceived actions and operates in a linear 
manner, it’s more limited in functionality than scripting. Automator is great for performing simple tasks 
involving a small number of sequential steps or apps. Scripting is a better choice for performing advanced, 
branching, or complex tasks. 


Python and Perl are other examples of scripting languages. 


AppleScript 


AppleScript is a mature scripting language developed by Apple. It’s relatively easy to learn in relation to other 
scripting and programming languages, has been around since System 7.1, and has been widely adopted in 
both enterprise and personal workflows. While the AppleScript scripting language uses an English-like 
terminology which may appear simple, it is a rich, object-oriented language, capable of performing 
complicated programming tasks. 


The core fundamentals of AppleScript are described in AppleScript Language Guide, as well as in numerous 
third-party books. 


JavaScript 


JavaScript is a popular cross-platform scripting language. Historically, it’s been most commonly used to 
implement features on websites and in web-based apps that are accessed through browsers. However, some 
apps implement JavaScript-based scripting models for the purpose of automation. In OS X 10.10, JavaScript 
became a peer to AppleScript in OS X. There are many third-party websites and books that document the 
JavaScript language. 


For fundamentals on JavaScript as a scripting language for automation in OS X, see JavaScript for 
Automation Release Notes. For information about the JavaScript language, see Mozilla’s official JavaScript 
documentation. 
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How Mac Scripting Works 


The Open Scripting Architecture (OSA) provides a standard and extensible mechanism for interapplication 
communication in OS X. This communication takes place through the exchange of Apple events. An Apple 
eventis a type of interprocess message that encapsulates commands and data. 


A scriptable application responds to Apple events by performing operations or supplying data. Every scriptable 
app implements its own scripting features and exposes its own unique terminology through a scripting 
dictionary. While not all apps are considered scriptable, any app with a graphical user interface responds to 
Apple Events at a minimal level. This is because OS X uses Apple Events to instruct all apps to perform core 
tasks such as launching, quitting, opening a document, and printing. To learn about scripting terminology and 
dictionaries, see Accessing Scripting Terminology. 


The OSA provides the following capabilities in OS X: 


* The ability for app developers to create scriptable apps and expose scripting terminology 
+ The ability for users to write scripts in a variety of scripting languages 


* The ability to communicate between apps on the same computer or on different computers using Apple 
events 


The Open Scripting framework defines standard data structures, routines, and resources for creating scripting 
components, which implement support for specific scripting languages. The AppleScript and JavaScript 
components (in System/Library/Components), for example, make it possible to control scriptable apps from 
AppleScript and JavaScript scripts. Through the framework’s standard interface, a scriptable app can interact 
with any scripting component, regardless of its language. The framework also provides API for compiling, 
executing, loading, and storing scripts—functions provided by script editing apps. 


The Apple Event Manager supplies the underlying support for creating scriptable apps and is implemented in 
the AE framework within the CoreServices framework. App developers can interact with the Apple Event 
Manager through the Apple Event APIs in the Foundation framework. See NSAppleEventManager Class 
Reference and NSAppleEventDescriptor Class Reference. 


Figure 2-1 shows how OSA elements work together in OS X. 


Figure 2-1 The Open Scripting Architecture workflow 
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Extending the Reach of Scripting 


Every scriptable app expands the reach of scripting. Developers can also add new scripting capabilities 
through scripting additions and scriptable background apps. 


A scripting addition is a bundle that implements new scripting terminology. For example, the Standard 
Additions scripting addition that comes with OS X (found in 
/System/Library/ScriptingAdditions/StandardAdditions.osax), includes commands for using the 
Clipboard, displaying alerts, speaking text, executing shell scripts, and more. Since scripting additions are 
loaded in a global context, commands provided by Standard Additions are available to all scripts. 


A scriptable background application (sometimes called an agent) runs with no visible user interface and 
provides scripts with access to useful features. System Events and Image Events are examples of scriptable 
background apps in OS X. Scripts can target System Events to perform operations on property list files, adjust 


system preferences, and much more. Scripts can target Image Events to perform basic image manipulations, 
such as cropping, rotating, and resizing. 


Objective-C Bridging 


Several technologies in OS X make it possible for scripts to interact with Objective-C frameworks, and vice- 
versa. 


AppleScriptObjC is a bridge between AppleScript and Objective-C, and JavaScriptObjC is a bridge between 
JavaScript for automation and Objective-C. These bridges enable you to write scripts that use scripting 
terminology to interact with Objective-C frameworks, such as Foundation and Appkit. The bridges also enable 
you to design user interfaces for scripts that have the same look and feel of any other Cocoa app. For 
information about the AppleScriptObjC bridge, see Objective-C to AppleScript Quick Translation Guide. For 
information about JavaScriptObjC, see Objective-C Bridge in JavaScript for Automation Release Notes. 


The Scripting Bridge lets you control scriptable apps using standard Objective-C syntax. Instead of 
incorporating scripts in your Cocoa app or dealing with the complexities of sending and handling Apple events, 
you can simply send Objective-C messages to objects representing scriptable apps. Your Cocoa app can do 
anything a script can, but in Objective-C code that’s more tightly integrated with the rest of your project’s code. 
See Scripting Bridge Programming Guide and Scripting Bridge Framework Reference. 
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Types of Scripts 


There are many different types of scripts on the Mac. 


Applets—A script that’s been saved as an app. It behaves like other apps. 
Double-click it to launch and run it. When an applet is launched, any code in its 


- run handler executes. If a script doesn’t contain an explicit run handler, then the 
yy top level of the script is treated as an implicit run handler and any code there 
executes. 


Droplets—A script applet that has been configured to accept dropped files and 
folders. Double-click it to launch and run it—execute its run handler. Or, drag and 
7 drop files and folders onto it to process them. In a droplet, dropped files and 
“2 folders are passed directly to an AppleScript open handler or JavaScript 
openDocuments function for processing. 


Scripts—A script document file. Double-click it to open it for editing. Some apps 
N and processes can load and run scripts. For example, Mail rules can execute 
scripts to process messages matching specific criteria. Scripts are sometimes 
referred to as compiled scripts. 





Script bundles—A script document that’s been saved in bundle format. A bundle 
* is a directory with a standardized, hierarchical structure that holds executable code 
and the resources used by that code. 


Stay-open scripts—By default, applets and droplets run and quit after launch. 
} When configured as stay-open, however, they remain open until explicitly ordered 
es to quit. Often, stay-open scripts include an idle handler, which initiates periodic 
actions. 


For detailed information about run, open, and idle handlers in AppleScript, see Handlers in Script Applications 
in AppleScript Language Guide. For information about run, openDocuments, and idle functions in JavaScript, 
see Applets in JavaScript for Automation Release Notes. For information about bundles, see Bundle 
Programming Guide. 
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About this Guide 


This guide provides high-level information about scripting on the Mac and isn’t designed to serve as a 
language guide. Primarily, it introduces core concepts, highlights resources, and provides examples that 
demonstrate common scripting tasks. 


This guide does not provide examples for every possible task that can be scripted in a given situation or app. 
For example, it doesn’t cover automating every single scriptable text manipulation function. Instead, it covers 
automating a range of commonly encountered scenarios, such as changing the case of text, splitting text, and 
adding a prefix to text. These examples can be used for guidance when attempting to automate other 
scriptable tasks. 


Many of the examples in this guide have been written modularly, allowing them to be copied and pasted into 
your own scripts, where they may be used as is or modified to meet your unique needs. Most examples are 
commented and relatively easy to follow, even with little or no prior scripting experience. 


The majority of examples in this guide are provided in both AppleScript and JavaScript format. A language 
label precedes each example, making its language easily distinguishable at a glance. Some examples 
demonstrate using the scripting bridges, AppleScriptObjC and JavaScriptObjC, to interact with Objective-C 
classes. Additional examples are occasionally provided in notes to show alternative solutions. 


NOTE 


Some examples in this guide require OS X 10.11 or later. 


Some JavaScript examples in this guide use template strings—string literals which may include embedded 
expressions, such as the one shown in Listing 4-1. 


JAVASCRIPT 
Open in Script Editor 


Listing 4-1 JavaScript: Example of a Template String with an embedded expression 


1 numberOfPeople = 12 
2 console. log(* There are ${numberOfPeople} people. *) 


Template strings were introduced as a JavaScript standard in 2015, and are supported in OS X 10.11 and 
later. 


Opening Examples in Script Editor 


Links have been provided throughout this guide to open example code directly in Script Editor. To open an 
example, click the “Open in Script Editor” link above a code listing. Depending on the security settings on your 
Mac, you may be prompted to confirm you want to open the script in Script Editor. If you receive this prompt, 
click the New Script button to create a new document. See Figure 4-1 and Figure 4-2. 


Figure 4-1 The dialog that opens when you click the “Open in Script Editor” link 


ee _Create New Calendar — Unidentified Developer 











New Script 


tell application "Calendar" 

set theCalendarName to “Project Calendar" 

set theCalendarDescription to "Calendar for top secret Apple project." 

set theNewCalendar to make new calendar with properties {name:theCalendarName, 
description: theCalendarDescription} 
end tell 





Figure 4-2 Example of a script that opens after you click the New Script button 





Create New Calendar — Edited » 


<No selected element> ¢ 





tell application "Calendar 
set theCalendarName to "Project Calendar" 
set theCalendarDescription to "Calendar for top secret Apple project." 
set theNewCalendar to make new calendar with properties {name:theCalendarName, 
description: theCalendarDescription} 
end tell 














NOTE 


New Script Editor documents are set to use your default scripting language, as configured in the General 
pane of Script Editor preferences. See Targeting a Scripting Language to learn how to configure an example 
script to target a different scripting language. 
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Getting to Know Script Editor 





Script Editor, found in /Applications/Utilities/, is an app for writing AppleScripts and JavaScripts. It 
provides the ability to edit, compile, and run scripts, browse scripting terminology, and save scripts in a variety 
of formats including compiled scripts, apps, and plain text. 


NOTE 


Xcode can also be used to write AppleScriptObjC and JavaScriptObjC apps. 


Navigating Script Editor Documents 


A Script Editor document window includes the following main areas, as shown in Figure 5-1: 


Figure 5-1 A Script Editor document window 
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Toolbar— Use this to compile, run, and stop your script. Buttons are also available for showing and 
hiding the accessory view pane and the bundle contents pane. Select View > Customize Toolbar, or 
Control-click on the toolbar and choose Customize Toolbar, to choose what buttons displayed in the 
toolbar. 


The toolbar also includes a Record button, which converts manual mouse clicks and keystrokes into 
script code. However, recording is not supported in JavaScript and few apps support AppleScript 
recording. 


Navigation bar—Use this bar to select a scripting language, target an app, or navigate through the 
handlers in your script. 


The navigation bar currently only supports navigation of AppleScript handlers. 
Editor pane—Write your script code here. 


Accessory View pane—View and edit your script’s description here, or browse the result and events 
produced when your script runs. 


- Bundle Contents pane— Edit the identifier, version, and copyright info for your script here. You can 
also use this pane to add, remove, or manage resources contained within the bundle. This pane is 
accessible only when your script is saved in script bundle or app format. 


Targeting a Scripting Language 


When you create a Script Editor document, select a scripting language in the navigation bar. See Figure 5-2. 


Figure 5-2 Setting the scripting language in a Script Editor document window 
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If you always use the same language, set it as the default in the General pane of Script Editor preferences. 
See Figure 5-3. 


Figure 5-3 Setting the default scripting language for Script Editor documents 
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Viewing Script Events and Results 


Script Editor can display the result of executing a script, as well as a log of events sent and received during 
execution. 


NOTE 
A result is a value generated when a script statement executes. For example, executing the make command 
to create a folder in the Finder produces the newly created folder object as its result. The result of a script is 
the result of the script’s last statement. If the script’s last statement doesn’t produce a result, then the script 


has no result. 


Viewing the Script Result 


The result of executing your script—if a result was produced—is found in the Accessory View pane. See 
Figure 5-4. 


Figure 5-4 Viewing the result of a script in Script Editor 
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Show Result button 


To view the result of your script 
Do one of the following: 
e Press Command-2. 
e Choose View > Show Result. 


* Click the Show Result ( <! ) button at the bottom of the Accessory View pane. 


Viewing the Script Log 


The Accessory View pane also contains a script log. See Figure 5-5. 


Figure 5-5 Viewing the script log in Script Editor 


eee |. Untitled — Edited » 
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AppleScript ¢ <No selected element> ¢ 


tell application "Finder" 
set theFolder to make new folder at desktop 
open theFolder 
return name of theFolder 

end tell 


Result Messages _—_ Events 


Script tell application "Finder" 
lo make new folder at desktop 
9 --> folder "untitled folder" of folder "Desktop" of 


folder "bwaldie" of folder "Users" of startup disk 
open folder "untitled folder" of folder "Desktop" of 
folder "bwaldie" of folder "Users" of startup disk 
get name of fo/der "untitled folder" of folder "Desktop" 
of folder "bwaldie" of fo/der "Users" of startup disk 
--> “untitled folder" 
end tell 


Result: 
“untitled folder" 








® «Je 


Show Log button 


The script log displays the following information. 


* Result—The result of executing your script. 
* Messages— Includes log messages generated as your script runs, as well as the script’s result. 


+ Events—Includes log messages, the script’s result, and events—commands-—sent to applications. 


Replies—Includes log messages, the script’s result, events sent to applications, and event replies. 


To view the script log 


Do one of the following: 


« Press Command-3. 
e Choose View > Show Log. 


* Click the Show Log ( [E] ) button at the bottom of the Accessory View pane. 


NOTE 


In AppleScript, log messages are generated using the Log command. See Listing 5-1. 
APPLESCRIPT 


Open in Script Editor 


Listing 5-1 AppleScript: Example of a log message at the root level of a script 


log "My log entry." 


Since the Log command targets the script itself, you must explicitly use the me keyword to direct it to the script 
when calling it within a tell statement. See Listing 5-2. 


APPLESCRIPT 
Open in Script Editor 


Listing 5-2 AppleScript: Example of a log message within an application tell statement 


1 tell app "Finder" 
2 tell me to log "My log entry." 
3 end tell 


In JavaScript, log messages are generated by calling the console. log() method anywhere in your script. 
See Listing 5-3. 


JAVASCRIPT 


Open in Script Editor 


Listing 5-3 JavaScript: Example of a log message 


console. log("My log entry.") 


Viewing the Log History 


The result and script log areas in the Accessory View pane reset each time you run your script. However, you 
can view historical logs for an opened script in the Log History window. See Figure 5-6. 


Figure 5-6 The Log History window in Script Editor 


eee Log History 


Pear 


Clear History Show Script 





Events Time Result Messages Events 
¥ Untitled 10:40:36 eq} application "Finder" 
Y tell application "Finder" —_— 10:40:36 make new folder at desktop with properties 
» make new folder at desk! 10:40:36 {name:"My Folder"} 
open folder "My Folder" 10:40:36 --> folder "My Folder" of folder "Desktop" 
¥ Untitled 10:34:40 of folder “bwaldie" of folder 
® tell application "Finder" 10:34:40 "Users" of startup disk 
“untitled folder" 10:34:41 open folder "My Folder" of folder "Desktop" of 
folder “bwaldie" of folder "Users" of 
startup disk 
end tell 


To view the Log History window 
Do one of the following: 
e Press Option-Command-L. 
e Choose View > Log History. 


* Click the Log History button ( © ) in the top right of the Accessory View pane. 
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Creating a Script 


Generally, most scripts are written in Script Editor documents. Scripts can also be written in Xcode, but this is 
typically for scripts that require advanced user interfaces. 
To write a script in Script Editor 

1. Launch Script Editor in /Applications/Utilities/. 

2. Press Command-N or select File > New. 


3. If the script isn’t configured for the correct language, choose the language in the navigation bar. 








eee 
e >is 
Vv AppleScript <No selected element> > 










JavaScript 


Te 


If you always use the same language, set it as the default language in the General pane of Script Editor 
preferences. See General Preferences. 


4. Write your script code in the editing area. Newly written code is uncompiled and formatted as new text. 
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5. Click the Compile button ( % ) to compile the script and check for syntax errors. 


If a syntax error occurs, an alert is displayed. 


Syntax Error 


Expected end of line, etc. but found property. 








If the script compiles, code formatting is applied at this time. 
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wile 


You can change the formatting attributes, such as font and color, of uncompiled and compiled text in the 
Formatting pane of Script Editor preferences. See Formatting Preferences. 


Using an AppleScript Template 


Script Editor includes a number of built-in templates for creating common types of AppleScripts, including 
droplets, Mail rule scripts, and Messages handler scripts. 


NOTE 


Script Editor does not include JavaScript templates at this time. 


To create a template-based script 
1. Launch Script Editor in /Applications/Utilities/. 


2. Choose File > New from Template. 


4 Script Editor [jsi) Edit View Script Font Format Window Help 
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3. Select a script template. 


A new Script Editor document window opens containing prewritten code and preconfigured settings. 
The following screenshot shows an example of a script created using a template. 
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4. Customize the script. 
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Saving a Script 


After you write a script, you can save it for future reference or to be run outside of Script Editor. 


Saving a Script or Script Bundle 
Scripts and script bundles open in Script Editor when double-clicked in the Finder. 


To save a script or script bundle 
1. Choose File > Save (or press Command-S) to display the save dialog. 
2. Type a name for the script and choose an output folder. 


3. Choose Script or Script Bundle from the File Format popup menu. 


Save As: My Script v 


Tags: 
Where: (| Desktop 
File Format:} Script 


Options: 


4. Click Save. 


Saving a Script Application 
Script applications, known as applets, work like other apps on your Mac. Double-click an applet to run it. 


To save an applet 
1. Choose File > Save (or press Command-S) to display the save dialog. 
2. Type a name for the applet and choose an output folder. 


3. Choose Application from the File Format popup menu. 


Save As: My Script App v 


Tags: 
Where: (|) Desktop 
File Format:| Application 


Options: Show startup screen 
Stay open after run handler 


4. If you want the script’s description—defined in the Accessory View pane—to display when the applet 
launches, select the “Show startup screen” checkbox. 


5. If you want to create a stay-open applet, select the “Stay open after run handler” checkbox. 


6. Click Save. 


NOTE 
To open a saved script applet or droplet for editing, drag it onto the Script Editor app or choose File > Open in 
Script Editor. 


To convert a previously saved script or script bundle to an applet, choose File > Duplicate, press Shift- 
Command-S, or choose File > Export. Then, perform the steps above. 


If an AppleScript applet contains an open event handler, or a JavaScript applet contains an openDocuments 
function, it automatically becomes a drag and drop application known as a droplet. Drag files and folders onto 
the droplet to process them, or double-click the droplet to run it. To learn about creating droplets, see 
Processing Dropped Files and Folders. 


Protecting a Script’s Source Code 


If you plan to distribute your script, you may wish to protect is source code. This is done by exporting the script 
in run-only format. 
To save a script in run-only format 

1. Choose File > Export to display the export dialog. 

2. Type a name for the applet and choose an output folder. 

3. Choose a format from the File Format popup menu. 

4. If you’re saving in application format, choose whether you want a startup screen or a stay-open script. 


5. Select the Run-only checkbox. 


Export As: My Run Only Script App v 


Tags: 
Where: (| Desktop 
File Format: Application 


Options: Show startup screen 


Stay open after run handler 
Run-only 


Code Sign: Don't Code Sign 


6. Click Save. 


IMPORTANT 


When saving a script in run-only format, make sure you retain a backup of your editable script. 


Code Signing a Script 


By default, the security settings in OS X only allow the launching of apps (including applets and droplets) that 
have been created by you, downloaded from the Mac App Store, or created by developers identified by Apple. 
If you plan to distribute your scripts to others, you should consider code signing your scripts with an Apple 
developer ID. 


You obtain a Developer ID certificate from Certificates, Identifiers & Profiles in your developer account and 
import it on your Mac. For detailed information about obtaining and importing a certificate, see Maintaining 
Your Signing Identities and Certificates in App Distribution Guide. 


To prepare a script application or bundle code signing 


1. If the Bundle Contents pane isn’t visible, choose View > Show Bundle, press Command-0, or click the 
bundle contents button ( [7] ) in the toolbar. 


2. Make sure the following highlighted fields are populated in the Bundle Contents pane. 


Bundle Info 


Name | My Script 
Identifier | com.myname.My-Script 


Short Version 


Bundle Version 


Copyright |} ©2015 My Company 


Scripting Definition 


Resources 


« description.rtfd 
> |) Scripts 


e Name—The name of your script. 


e Identifier—A uniform type identifier for your script. For information, see Uniform Type Identifiers 
Overview. 


e Short Version—The version number for your script. 


e Copyright—The copyright string for your script. 


To code sign a script 
1. Choose File > Export to display the export dialog. 
2. Type a name for the applet and choose an output folder. 
3. Choose a format from the File Format popup menu. 
4. If you’re saving in application format, choose whether you want a startup screen or a stay-open script. 
5. Choose whether you want to save the script as run-only. 


6. Choose your developer identity from the Code Sign popup menu. 


Export As: My Run Only Script App v 


Tags: 
Where: (| Desktop 
File Format: Application 


Options: Show startup screen 
Stay open after run handler 
Run-only 


Code Sign:} Don’t Code Sign 


7. Click Save. 
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Running a Script 


Scripts can be opened and run in Script Editor and script applications can be run outside of Script Editor like 
any other OS X application. Some apps and tools, such as Automator and the systemwide script menu, can 
also run scripts. 


Running a Script in Script Editor 
To run a script in Script Editor, click the Run button ( @ ) in the toolbar, press Command-R, or choose Script > 


Run, as shown in Figure 8-1. 


Figure 8-1 Running a script in Script Editor 


View Font Format Window 


Record TR 
Run sR 
Compile HK 


As the script runs, the Accessory View pane shows events and results of the script. This information can be 
useful for troubleshooting. See Viewing Script Events and Results. 


Running a Script Application 


To run a script application, double-click the script in the Finder, just like you would do to launch any other 
application. The script opens and begins running. 


NOTE 


When running a script app outside of Script Editor, you can’t view a list of the script’s events and results. To 
monitor this activity, open the app in Script Editor instead, run it, and check the Accessory View pane. 
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Configuring Scripting Preferences 


Script Editor preferences allows you to configure a variety of aspects of scripting behavior. 


General Preferences 


In the General pane of Script Editor preferences (Figure 9-1), you can configure settings such as the following. 


Figure 9-1 General pane of Script Editor preferences 
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SSSI Editing Formatting History Plug-Ins _ 
Default Script Editor: _/ Script Editor (2.7) 
Default Language: AppleScript (2.4) 
Default Target: Show “tell” application menu 
Dictionary Viewer: Show inherited items 


Script Menu: Show Script menu in menu bar 
Show Computer scripts 


Show application scripts: at top 
Oat bottom 








Default Language—The default scripting language when you create new Script Editor documents. 


Show “tell” application menu—This setting can be enabled to add a tell application menu to the navigation 
bar. Selecting an app in this menu allows you to direct script execution to the chosen app. In Figure 9-2, the 
tell application menu is set to the Finder. As a result, the script itself doesn’t need to include a tell 


application "Finder" statement. It automatically understands the Finder’s terminology and sends events to 
the Finder. 


Figure 9-2 The tell application menu in a Script Editor document 
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In addition, the current application object—which refers to the application currently executing the script— 
reflects the selected application, rather than Script Editor. See Listing 9-1 and Listing 9-2. 


APPLESCRIPT 


Open in Script Editor 
Listing 9-1 AppleScript: Targeting the current application object after setting the tell application menu in Script Editor to Finder 


1 name of current application 


2 --> Result: "Finder" 


JAVASCRIPT 
Open in Script Editor 
Listing 9-2 JavaScript: Targeting the current application object after setting the tell application menu in Script Editor to Finder 


1 Application. currentApplication().name() 
2 // Result: "Finder" 


Show inherited items—This setting can be enabled to display inherited object properties in the dictionary 
viewer. For example, in the Finder, a file object inherits the attributes of an item object. Without this setting 
enabled, the dictionary entry for file simply provide a a pointer to the item entry to view the item attributes. 
See Figure 9-3. With this option enabled, the file entry in the Finder’s scripting dictionary includes the 
attributes of an item. See Figure 9-4. 


Figure 9-3 Dictionary entry without inherited items 





eco & Finder 
y & te Q Ter 
< AA Ge & Appescriot BS Q 0 
Back/Forward Text Size view Language Print ‘Search 
Ey stencars Sue > ET (60° 
(Ei Finger Basics » Galas file > [i creator type 
[Bi Finder items » [application fite » [lJ stationery 
[Ei Containers and folders » [document file [Gi product version 
Giles > G internet location tile » [version 
[Bi Window classes » [clipping > 
[Bi Legacy suite » [package 
(Ei Type Definitions > 


file ni [inh. item] : A file 
PROPERTIES, 
file type (type) : the OSType identifying the type of data contained in the item 
creator type (type) : the OSType identifying the application that created the item 


stationery (boolean) : Is the file a stationery pad? 
Product version (text, r/o) : the version of the product (visible at the top of the "Get Info” window) 
version (text, r/o) : the version of the file (visible at the bottom of the “Get Info” window) 





alias file 7 [inh, file > item] : An alias file (created with “Make Alias”) 


PROPERTIES 
original item (specifier) : the original item pointed to by the alias 


application file n [inh. file > item] : An application's file on disk 
PROPERTIES. 
id (text, r/o) : the bundle identifier or creator type of the application 
suggested size (integer, r/o) : (AVAILABLE IN 10.1 TO 10.4) the memory size with which the developer recommends the application 
be launched 
minimum size (integer) ; (AVAILABLE IN 10.1 TO 10.4) the smallest memory size with which the application can be launched 
preferred size (integer) : (AVAILABLE IN 10.1 TO 10.4) the memory size with which the application will be launched 
accepts high level events (boolean, r/o) : Is the application high-level event aware? (OBSOLETE: always returns true) 
has scripting terminology (boolean, r/o) : Does the process have a scripting terminology, i.e., can it be scripted? 


one in Classic (aealean 2 (annaore IN 10.1 TO 20) Should the spp ezien launch in the Classic environment? 


Figure 9-4 Dictionary entry with inherited items 





ece [8 Finder 
a = QT. 
< AA ig) | AppleScript B —) Q Tei 
Back/Forward Text Size View Language Print ‘Search 
Gy Suncare Suite TS Gc 1° 
i Finder Basics » Galas tie > [ij creator type 
[Bi Finder itoms » application file » [Bj stationery 
Containers and folders » [document fle Gi product version 
S Files & [@ internet location tile » El version 
[Bi Window classes » Giclipping > 
(Bj Legacy suite » [package 
Bi Type Definitions > 


file n [inh, item] : A file 
mmovenries 
file type (type) : the OSType identifying the type of data contained in the item 
‘creator type (type) : the OSType identifying the application that created the item 
stationery (boolean) : Is the file a stationery pad? 
product version (text, r/o) : the version of the product (visible at the top of the “Get Info” window) 
version (text, r/o) : the version of the file (visible at the bottom of the "Get Info” window) 


INHERITED FROM ITEM 


SEMENTS 
contained by application, containers, disks, folders, desktop-objects, trash-objects. 
PROPERTIES 

mame (text) : the name of the item 

displayed name (text, r/o) : the user-visible name of the item 

name extension (text) : the name extension of the item (such as “txt") 
extension hidden (boolean) : Is the item's extension hidden from the user? 


index (integer, r/o) : the index in the front-to-back ordering within its container 

container (specifier, r/o) : the container of the item 

disk (specifier, r/o) : the disk on which the item is stored 

Position (point) : the position of the item within its parent window (can only be set for an item in a window viewed as icons or 


buttons) 
desktop position (point) : sition of the item on the desktop 





Script Menu—These settings allow you to enable and configure a systemwide script menu (Figure 9-5). This 
menu can be used to organize your scripts and provide access to them in any app. 


Figure 9-5 The systemwide script menu 
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Editing Preferences 


In the Editing pane of Script Editor preferences, shown in Figure 9-6, you can configure settings such as the 
following. 


Figure 9-6 Editing pane of Script Editor preferences 


@eec Editing 
| ® © # 
General Formatting History Plug-ins 





Code completion: Suggest completions while typing 
Tab width: 4 spaces 


Line wrapping: Wrap lines to editor width 
Indent wrapped lines by: 4 spaces 


Formatting: | Escape tabs and line breaks in strings 





Code completion—When this option is enabled, Script Editor suggest code completions as you type a script 
(Figure 9-7). 


Figure 9-7 Code completion in Script Editor 
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To accept and insert a code completion suggestion, press the F5 key or the Esc (Escape) key. If multiple code 
completion choices are available, a code completion dialog appears, allowing you to select a suggestion (see 
Figure 9-8). 


Figure 9-8 The code completion dialog in Script Editor 
tell application... 


@ application file 
Gi application process 


Tab width and line wrapping — Adjust how indentation and line wrapping occurs in the editor pane of Script 
Editor documents. 


Escape tabs and line breaks in strings—This setting only affects AppleScripts. When this option is disabled, 
tabs and line breaks appear normally in a text string, as shown in Figure 9-9. 


Figure 9-9 A string containing normal tabs and line breaks 
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set theText to “This is line 1. 


This is line 2. 
This is a tab-indented line 3." 





Description 




















When this option is enabled, tabs and line breaks are replaced with escaped character equivalents—/t fora 
tab, and /r for a line break. See Figure 9-10. 


Figure 9-10 A string containing escaped tabs and line breaks 


eco 2 Untitled — Edited ~ 
oj iz S 
AppleScript > _ tell current application S _<No selected element> > ; 
set theText to "This is line 1.\nThis is line 2.\n\tThis is a tab-indented line 3.” 








Description 




















Formatting Preferences 


In the Formatting pane of Script Editor window (Figure 9-11), you can configure the style—font, point size, and 
color—of various script attributes, including new text, language keywords, comments, and variables. 
Formatting options are language-specific. Select a language from the Language popup menu to view that 
language’s formatting settings. 


Figure 9-11 Formatting pane of Script Editor preferences 
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General Editing Formatting History Plug-ins 


Language: AppleScript 


Addition classes Verdana Italic 12 
Addition properties Verdana 12 
Addition enumerated values Verdana Italic 12 


Category Font Size Color 
New text (uncompiled) Menlo Regular 12 Ea 
Operators, etc. (+ & ,) Verdana 12 aa 
Language keywords Verdana Bold 12 | | 
Application keywords Verdana 12 | 
Comments Verdana 12 | 
Values (numbers, data) Verdana 2 i 
Variables and subroutine names Verdana 12 Es 
Strings Verdana 12 | | 
Command names Verdana Bold 12 Ly 
Parameter names Verdana 12 == 
Classes Verdana Italic 12 | 
Properties Verdana 12 = 
Enumerated values Verdana Italic 12 Eg 
Addition command names Verdana Bold 12 | | 
Addition parameter names Verdana 12 SExy 
mw 
= 


Use Defaults t 








History Preferences 


In the History pane of Script Editor preferences (Figure 9-12), you can enable or disable the log history, adjust 
the quantity of log history entries, and enable logging only when the log is visible. 


Figure 9-12 History pane of Script Editor preferences 


ee History 


General Editing Formatting History Plug-ins 


Log History: (& Enable Log History 
Unlimited entries 
© Maximum entries: 10 


Logging: Log only when visible 








Plug-ins Preferences 


The Plug-ins pane of Script Editor preferences (Figure 9-13) lists any installed Script Editor plug-ins. 


Figure 9-13 Plug-ins pane of Script Editor preferences 














Copyright © 2018 Apple Inc. All rights reserved. Terms of Use | Privacy Policy | Updated: 2016-06-13 


About Scripting Terminology 


AppleScript and JavaScript possess core language commands, classes, and properties that make scripting 
possible. For AppleScript, core terminology is documented in AppleScript Language Guide. For JavaScript, 
see JavaScript for Automation Release Notes and Mozilla’s official JavaScript documentation. 


Each scriptable app introduces additional terminology that extends the core language. For example, Mail 
introduces terminology for creating and sending email messages. iTunes introduces terminology for working 
with music and playlists. In order to write a script that controls an app, you need to familiarize yourself with that 
app’s terminology. 


The terminology for an app is found in its scripting dictionary, an .sdef file stored in the app bundle. The 
dictionary describes the commands, classes, and properties an app supports. This information is used by the 
scripting components of the operating system, the app itself, and any other apps or scripts that interact with 
the app through scripting. It also serves as a reference, which you can consult in Script Editor for guidance as 
you write a script. See Figure 10-1. 


Figure 10-1 Example of a scripting dictionary in Script Editor 





eee © Finder 
= ‘ g O acer 
< AA | ® % AppleScript c— Q Terminology 
Back/Forward Text Size View Language Print Search 
© Standard Suite 
|B Finder Basics 
|S) Finder items. 
|) Containers and folders > @activate 
|GiFiles > @close 
|B Window classes » @ count 
|B) Legacy suite > @ data size 
Type Definitions > @delet 
>< 
Standard Suite Common terms that most applications should support 


open v : Open the specified object(s) 


open specifier : list of objects to open 
[using specifier] : the application file to open the object with 
[with properties record] : the initial values for the properties, to be included with the open command 
sent to the application that opens the direct object 


print v : Print the specified object(s) 


print specifier : list of objects to print 
[with properties record] : optional properties to be included with the print command sent to the 
application that prints the direct object 


quit v : Quit the Finder 
quit 








Not every OS X app supports scripting, but many apps do, including Mail, Address Book, Calendar, iTunes, 
and Messages. To determine if a particular app is scriptable, see if it has a scripting dictionary. See Opening a 
Scripting Dictionary. 


Scripting terminology can vary extensively from app to app. While some apps may have extensive scripting 
support, others may have very limited scripting support. If an app doesn’t meet your scripting needs, reach out 
to the app developer and request improved support in a future version. To request scripting enhancements for 
Apple apps, submit a bug report that specifies the app and communicates your specific needs. 


Also, keep in mind that scripting terminology can change from one version of an app or OS X to the next. 
Always test essential scripts when upgrading to a new app or system version. 


NOTE 
OS X also supports scripting additions, packages of terminology that extend the core AppleScript language. 
In fact, OS X comes with Standard Additions, a scripting addition that implements a range of commonly 
performed functions, such as displaying alerts and dialogs, speaking text, and reading and writing files. 
Scripting additions are installed in /System/ScriptingAdditions/, /Library/ScriptingAdditions/, or 
~/Library/ScriptingAdditions/, and have dictionaries just like scriptable apps. 
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Opening a Scripting Dictionary 


Script Editor can open dictionaries and display their contents for you to consult while writing scripts. 


To open a scripting dictionary in Script Editor 


Do one of the following: 
e Drag an app or scripting addition onto Script Editor in the Dock or in the Finder. 





Script Editor 


¢ Choose File > Open Dictionary (or press Shift-Command-O), and select a scriptable app or scripting 


addition. 


@ = ScriptEditor FN) Edit View Script Font 


New 38N 
New from Template > 
Open... #0 
Open Dictionary... t#O 
Open Recent > 
Close sW 
Revert To > 


e Double-click an app or scripting addition in the Library palette. If the Library palette isn’t visible, choose 
Window > Library (or press Shift-Command-L) to display it. Click the Add button (+) in the Library 
palette to add a new app or scripting addition to the list for quick access in the future. 


@@@ Library 
oo. 


{1 Calendar 

1B Contacts 
Database Events 
= DVD Player 


\B Font Book 
Image Events 
(® iTunes 

© Keynote 

®& mail 

@ Messages 








An error message is displayed if you attempt to open an app without scripting terminology—a nonscriptable 


app. 





(— Add Item 
Unable to add the item because it is not scriptable. 
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Navigating a Scripting Dictionary 
A scripting dictionary window in Script Editor contains three primary areas. See Figure 12-1. 


Figure 12-1 Primary elements of a scripting dictionary window in Script Editor 


View by suite, 
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or inheritance Scripting language Search field 
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Navigation pane frie lps 
|S) Window classes >» @count 
(Bi Legacy suite > @ data size 
|) Type Definitions > @ delete 
! Pr stuentinnnn 
Standard Suite Common terms that most applications should support 


open v : Open the specified object(s) 


open specifier : list of objects to open 
[using specifier] : the application file to open the object with 
[with properties record] : the initial values for the properties, to be included with the open command 
sent to the application that opens the direct object 


Detail pane 
print v : Print the specified object(s) 


print specifier : list of objects to print 
[with properties record] : optional properties to be included with the print command sent to the 
application that prints the direct object 


quit v : Quit the Finder 
quit 








* Toolbar. Options for toggling between terminology views, setting the scripting language, entering search 
terms, and more. 


* Navigation pane. Columns of scripting terminology. 


* Detail pane. Definitions for any terminology selected in the navigation pane. 


Types of Terminology 
The navigation pane of a dictionary includes the types of terms described in Table 12-1. 


Table 12-1 Types of scripting terminology 
Type Icon Description 


A Suite is a grouping of related commands and classes. Apps 
. often have a Standard Suite, which includes terminology 
Suite F 
supported by most scriptable apps, such as an open 
command, a quit command, and an application class. 


A command is an instruction that can be sent to an app or 
object in order to initiate some action. For example, delete, 


Command make, print are commands that are found in many scriptable 


apps. Many commands have parameters that specify the 
target object and control the behavior of the command. 


A class is an object within an app, or an app itself. Mail, for 
example, has an application class, a message class, anda 
signature class, among others. Objects within an app 
Glee sometimes contain other objects as elements. For example, 
in Mail, a mailbox objects can contain message objects as 


elements. 


ae 


A property is an attribute of a class. For example, the message 
class in Mail has many properties, including date received, 


Propert : 
pay read status, and subject. Some properties are read-only, 


while others are readable and writable. 


Key Concepts 


It’s important to understand the concepts of inheritance and containment when navigating a scripting 
dictionary. 


Inheritance 


In a scriptable app, different classes often implement the same properties. For example, in Finder, the file 
and folder classes both have creation date, modification date, and name properties. Rather than defining 
these same properties multiple times throughout the scripting dictionary, Finder implements a generic item 
class. Since files and folders are considered types of Finder items, these classes inherit the properties of the 
item class. In other words, any properties of the item class also apply to the file and folder classes. There 
are many other items in Finder that also inherit these same properties, including the disk, package, and alias 
file classes. 


A class that inherits the properties of other classes can also implement its own properties. In Finder, the file 
class implements a number of file-specific properties, including file type and version. The alias file class 
implements an original item property. 


In some cases, a class inherits properties from multiple classes. In Finder, an alias is a type of file, which is a 
type of item. Therefore, the alias file class inherits the properties of both the file and item classes, as 
shown in Figure 12-2. 


Figure 12-2 In scripting, classes can inherit the properties of other classes 
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|_ modification date | modification date 
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Containment 


Classes of a scriptable app reside within a certain containment hierarchy. The application is at the top level, 
with other classes nested beneath. Finder, for example, contains disks, folders, files, and other objects. While 
files don’t contain elements, folders and disks can contain other folders and files. See Figure 12-3. Mail is 
another example—the application contains accounts, which can contain mailboxes, which can contain other 
mailboxes and messages. 


Figure 12-3 In scripting, classes can contain other classes as elements 





When referencing a class, you must do so very specifically according to its containment hierarchy in order to 
provide the scripting system with context. To reference a file in Finder, you would specify where the file resides 


in the folder hierarchy. See Listing 12-1 and Listing 12-2. To reference a message in Mail, you would specify 
where the message resides in the mailbox and account hierarchy. 


APPLESCRIPT 
Open in Script Editor 
Listing 12-1 AppleScript: Referencing a file by containment hierarchy in Finder 


i tell application "Finder" 


2 modification date of file "My File.txt" of folder "Documents" of folder 
"YourUserName" of folder "Users" of startup disk 

3 end tell 

4 --> Result: date "Monday, September 28, 2015 at 10:10:17 AM" 

JAVASCRIPT 


Open in Script Editor 
Listing 12-2 JavaScript: Referencing a file by containment hierarchy in Finder 


i var Finder = Application("Finder") 

2 Finder. startupDisk. folders ["Users"]. folders ["YourUserName"]. folders ["Documents"].fil 
es["My File.txt"].modificationDate() 

3 // Result: Mon Sep 28 2015 17:10:17 GMT-0700 (PDT) 


Anatomy of a Command Definition 


The definition of acommand in a scripting dictionary is a recipe for using the command, as shown in Figure 
12-4, Listing 12-3, and Listing 12-4. 


Figure 12-4 Definition for the move command in the Finder scripting dictionary 


Direct parameter 


Command —— move v : Move object(s) to a new location 


move specifier : the object(s) to move 


Required labeled to location specifier : the new location for the object(s) 








parameter [replacing boolean] : Specifies whether or not to replace items in the destination 
that have the same name as items being moved 
Optional labeled [positioned at list] : Gives a list (in local window coordinates) of positions for the 
parameters destination items 
{routing suppressed boolean] : Specifies whether or not to autoroute items 
(default is false). Only applies when moving to the system folder. 
Result — specifier : to the object(s) after they have been moved 





Parameter type 


A command definition includes the following elements: 


Command name. The name of the command. 


Direct parameter. An object to be targeted by the command. For the move command in Finder, this is 
the object to be moved. If a command definition doesn’t specify a direct parameter, then the target object 
is the application. A direct parameter immediately follows the command. 


Labeled parameters. Control some aspect of the command's behavior and are required or optional. 
Optional parameters are surrounded by brackets. Since these parameters are identified by label, they 
can be placed in any order when you write your script. The command definition denotes the value type 
for each labeled parameter. For example, the optional replacing parameter for the move command in 
Finder takes a boolean value. 


Result. The result of the command, if any. Often, this is a reference to a newly created or modified 
object. For the move command in Finder, it’s a reference to the moved object. 


APPLESCRIPT 
Open in Script Editor 
Listing 12-3 AppleScript: Example usage of the move command in Finder 


i tell application "Finder" 


2 move folder someFolder to someOtherFolder replacing true 
3 end tell 


JAVASCRIPT 
Open in Script Editor 
Listing 12-4 JavaScript: Example usage of the move command in Finder 


var Finder = Application("Finder") 
Finder.move(someFolder, { 
to: someOtherFolder, 


replacing: true 


wn F&F WN BP 


}) 


Anatomy of a Class Definition 


A class definition describes a class, as shown in Figure 12-5. 


Figure 12-5 Definition for the mailbox class in the Mail scripting dictionary 


Class 





mailbox rn, p/ mailboxes : A mailbox that holds messages 








é ‘ ELEMENTS 
Containment details contains mailboxes, messages; contained by application, accounts, mailboxes. 


PROPERTIES 
name (text) : The name of a mailbox 
Properties unread count (integer, r/o) : The number of unread messages in the mailbox 
account (account, r/o) 
container (mailbox, r/o) 


| tL Read-only property indicator 


Property type 





A class definition includes the following elements: 


Class name. The name of the class. 


Inheritance details. A list of other classes from which properties are inherited, if any. Each class is a 
hyperlink —clicking it takes you to the definition for the corresponding class. 


Containment details. A list of contained classes, if any. May also list other classes containing the class, 
if any. 


Properties. Any properties for the class, along with their data types. Read-only properties include an 
r/o indicator. 


To view inherited properties, as well as containing classes in the Script Editor dictionary viewer, select Show 
inherited items in Preferences > General. See Figure 12-6. 


Figure 12-6 Enabling inherited item dictionary details in Script Editor 


ee General 
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General Editing Formatting History Plug-ins 


Default Script Editor: _/ Script Editor (2.8) 


Default Language: AppleScript (2.5) 
Default Target: Show “tell” application menu 


Dictionary Viewer: Show inherited items 


Script Menu: Show Script menu in menu bar 
Show Computer scripts 





Show application scripts: at top 
Oat bottom 
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Using Handlers/Functions 


Collections of script statements that can be invoked by name are referred to as handlers in AppleScript, 
functions or methods in JavaScript, and subroutines in some other languages. Throughout this document, 
these terms are used interchangeably. 


Handlers are generally written to perform a task multiple times throughout a script, such as displaying an alert, 
writing text to a file, or creating an email message. Instead of inserting the same code over and over, you write 
it once and give ita name. You can name a handler whatever you like as long as the name contains no special 
characters, such as punctuation, or spaces, and isn’t a reserved language term. You then call, or evoke, a 
handler whenever necessary by referring to it by name. Each time you do, any code in the handler runs. 
Handlers can optionally be written to receive information as input for processing (parameters), and can return 
information as output (result or return value). 


Handlers provide a way to organize your code by breaking it up into smaller, manageable, modular chunks. 
This can be useful when troubleshooting; you can narrow in on a single handler to resolve a problem, rather 
than sorting through a long, complex script. It also makes future script updates easier, as you can change 
behavior in one place to affect an entire script. 


NOTE 


AppleScript handlers are generally placed at the end of a script, while in JavaScript, they’re usually placed at 
the top. 


AppleScript Handlers 


In AppleScript, a handler begins with the word on or to, followed by the handler name and its parameters, if 
any. It ends with the word end, followed by the handler name. AppleScript handlers can be written with 
positional, labeled, or interleaved parameters. 


Listing 13-1 shows a simple one-line script that displays a hypothetical error message, which you might want 
to display numerous times as a script runs. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-1 AppleScript: A simple script that displays an error message 


display dialog "The script encountered a problem." 


In Listing 13-1, the code from Listing 13-1 has been converted to a handler named displayError, which has 
no parameters. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-2 AppleScript: A simple handler that displays an error message 


1 on displayError() 
2 display dialog "The script encountered a problem." 


3 end displayError 


Listing 13-3 shows a variation of the handler in Listing 13-1, which uses the to prefix instead of on. Either 
syntax is acceptable. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-3 AppleScript: A variation of a simple handler that displays an error message 


1 to displayError() 
2 display dialog "The script encountered a problem." 


3 end displayError 


You can now call the displayError handler any time you want to display an error, as shown in Listing 13-4. 
APPLESCRIPT 
Open in Script Editor 


Listing 13-4 AppleScript: Calling a simple handler to display an error message 


1 try 

2 -- Do something 

3 on error 

4 -- Notify the user that there's a problem 
5 displayError() 

6 end try 

7 

8 try 

9 -- Do something else 

10 on error 

11 -- Notify the user that there's a problem 
12 displayError() 

13 end try 


For detailed information about AppleScript handlers, see About Handlers and Handler Reference in 
AppleScript Language Guide. 


NOTE 


To call a handler from within a tell statement, you must use the reserved words of me or my, as shown in 
Listing 13-5. 


APPLESCRIPT 


Open in Script Editor 


Listing 13-5 AppleScript: Calling a handler from within a tell statement 


1 tell application "Finder" 
2 try 
3 -- Do something 
4 on error 
5 -- Notify the user that there's a problem 
6 displayError() of me 
7 end try 
8 end tell 
9 
10 
11 tell application "Finder" 
12 try 
13 -- Do something else 
14 on error 
15 -- Notify the user that there's a problem 
16 my displayError() 
17 end try 


18 end tell 


AppleScript Handlers with Positional Parameters 


Positional parameters are a series of comma-separated variables, contained within parentheses, following the 
handler name. In Listing 13-6, the displayError handler from Listing 13-1 has been updated to accept two 
positional parameters—an error message and a list of buttons to display. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-6 AppleScript: A handler that displays a specified error message with custom buttons 


1 on displayError(theErrorMessage, theButtons) 
2 display dialog theErrorMessage buttons theButtons 
a end displayError 


To call the handler, refer to it by name and provide a value for each positional parameter, as shown in Listing 
13-7. The order of these values should match the parameter positions in the handler definition. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-7 AppleScript: Calling a handler to display a specified error message with custom buttons 


displayError("There's not enough available space. Would you like to continue?", 


{"Don't Continue", "Continue"}) 


For additional information about this style of handler, see Handlers with Positional Parameters in AppleScript 
Language Guide. 


AppleScript Handlers with Interleaved Parameters 


Interleaved parameters are a variation of positional parameters, in which the parameter name is split into 
pieces and interleaved with parameters using colons and spaces. Listing 13-8 shows how the handler from 
Listing 13-6 can be represented using interleaved parameters. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-8 AppleScript: Example of a handler with interleaved parameters 
1 tell me to displayError:"There's not enough available space. Would you like to 


continue?" withButtons:{"Don't Continue", "Continue"} 


on displayError:theErrorMessage withButtons: theButtons 


display dialog theErrorMessage buttons theButtons 
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end displayError:withButtons: 


Interleaved parameters resemble Objective-C syntax. Therefore, they are typically used to call Objective-C 
methods in AppleScriptObjC scripts. 


Objective-C to AppleScript Quick Translation Guide discusses interleaved parameter use in AppleScriptObjC 
scripts. For additional information about this style of handler, see Handlers with Interleaved Parameters in 


AppleScript Language Guide. 


AppleScript Handlers with Labeled Parameters 


AppleScript also supports labeled parameters, although this style is rarely used when defining custom 
handlers. Most often, it’s a style used for event handlers. See Event Handlers. Listing 13-9 shows how the 
displayError handler might appear if it were written using the labeled parameter style. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-9 AppleScript: Example of a handler with labeled parameters 


ii display of "There's not enough available space. Would you like to continue?" over 


{"Don't Continue", "Continue"} 


to display of theErrorMessage over theButtons 
display dialog theErrorMessage buttons theButtons 


end display 


For additional information about this style of handler, see Handlers with Labeled Parameters in AppleScript 
Language Guide. 


JavaScript Functions 


In JavaScript, a function name is preceded by the word function and followed by a list of parameters, if any. 
The function’s contents are contained within curly braces ({ ... }). 


Listing 13-10 shows a simple script that displays a hypothetical error message. 
JAVASCRIPT 

Open in Script Editor 

Listing 13-10 JavaScript: A simple function that displays an error message 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


1 

2 

3 

4 function displayError() { 

5 app.displayDialog("The script encountered a problem.") 
6 


You can now call the displayError function any time you want to display an error, as shown in Listing 13-11. 
JAVASCRIPT 
Open in Script Editor 


Listing 13-11 JavaScript: Calling a simple function to display an error message 


1 try { 

2 // Do something 

3} catch (error) { 

4 // Notify the user that there's a problem 
5 displayError() 

6 } 

7 

8 try { 

9 // Do something else 


10 } catch (error) { 


11 // Notify the user that there's a problem 
12 displayError() 
13 + 


Using Parameters 


JavaScript functions are written with positional parameters, comma-separated variables, contained within 
parentheses, following the function name. In Listing 13-12, the displayError function from Listing 13-10 has 
been updated to accept two positional parameters—an error message and a list of buttons to display. 


JAVASCRIPT 
Open in Script Editor 
Listing 13-12 JavaScript: A function that displays a specified error message with custom buttons 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


app.displayDialog(errorMessage, { 
buttons: buttons 


1 
2 
3 
4 function displayError(errorMessage, buttons) { 
5 
6 
7 }) 

8 


To call the function, refer to it by name and provide a value for each positional parameter, as shown in Listing 
13-13. The order of these values should match the parameter positions in the function definition. 


JAVASCRIPT 
Open in Script Editor 


Listing 13-13 JavaScript: Calling a function to display a specified error message with custom buttons 


displayError("There's not enough available space. Would you like to continue?", 


["Don't Continue", "Continue"] ) 


Exiting Handlers and Returning a Result 


Often, handlers are used to process information and produce a result for further processing. To enable this 
functionality, add the return command, followed by a value to provide, to the handler. In Listing 13-14 and 
Listing 13-15, the displayError handler returns a Boolean value, indicating whether processing should 
continue after an error has occurred. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-14 AppleScript: Returning a value from a handler 


i set shouldContinueProcessing to displayError("There's not enough available space. 


Would you like to continue?") 





2 if shouldContinueProcessing = true then 
3 -- Continue processing 
4 else 
5 -- Stop processing 
6 end if 
7 
8 on displayError(theErrorMessage) 
9 set theResponse to display dialog theErrorMessage buttons {"Don't Continue", 
"Continue"} default button "Continue" 
10 set theButtonChoice to button returned of theResponse 
11 if theButtonChoice = "Continue" then 
12 return true 
13 else 
14 return false 
15 end if 
16 end displayError 
JAVASCRIPT 


Open in Script Editor 
Listing 13-15 JavaScript: Returning a value from a function 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


function displayError(errorMessage) { 
var response = app.displayDialog(errorMessage, { 
buttons: ["Don't Continue", "Continue"], 
defaultButton: "Continue" 
3) 
var buttonChoice = response. buttonReturned 


if (buttonChoice == "Continue") 


return true 


else 


1 
2 
3 
4 
5 
6 
7 
8 
9 
1) 
1 
2 
13 return false 
14 
15 
16 var shouldContinueProcessing = displayError("There's not enough available space. 
Would you like to continue?") 


17 if (shouldContinueProcessing) { 





18 // Continue processing 
19 } else { 
20 // Stop processing 


NOTE 


You can return a value at any time within a handler, not just at the end. 


Event Handlers 


Some apps, including scripts themselves, can call handlers when certain events occur, such as when 
launched or quit. In Mail, you can set up a rule to look for incoming emails matching certain criteria. When a 
matching email is detected, Mail can call a handler in a specified script to process the email. Handlers like 
these are considered event handlers or command handlers. 


Listing 13-16 shows an example of a Mail rule event handler. It receives any detected messages as input, and 
can loop through them to process them. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-16 AppleScript: Example of a Mail rule event handler 


using terms from application "Mail" 
on perform mail action with messages theDetectedMessages for rule theRule 
tell application "Mail" 


set theMessageCount to count of theDetectedMessages 


set theCurrentMessage to item a of theDetectedMessages 
-- Process the message 


1 
2 
3 
4 
5 repeat with a from 1 to theMessageCount 
6 
7 
8 end repeat 

9 


end tell 
10 end perform mail action with messages 


11 end using terms from 


Script Event Handlers 

As previously mentioned, scripts can contain event handlers too. These handlers run when certain events 
occur. 

Run Handlers 


The run event handler is called when a script runs. By default, any executable code at the top level of a script 
—that is, not contained within a handler or script object—is considered to be contained within an implicit run 
handler. See Listing 13-17 and Listing 13-18. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-17 AppleScript: Example of an implicitly defined run handler 


display dialog "The script is running." 


JAVASCRIPT 
Open in Script Editor 
Listing 13-18 JavaScript: Example of an implicitly defined run function 


1 var app = Application. currentApplication() 
2 app.includeStandardAdditions = true 
2 app.displayDialog("The script is running.") 


Optionally, the run handler can be explicitly defined. Listing 13-19 and Listing 13-20 produce the exact same 
behavior as Listing 13-17 and Listing 13-18. 


APPLESCRIPT 


Open in Script Editor 


Listing 13-19 AppleScript: Example of an explicitly defined run handler 


1 on run 
2 display dialog "The script is running." 


3 end run 
JAVASCRIPT 


Open in Script Editor 


Listing 13-20 JavaScript: Example of an explicitly defined run function 


1 function run() { 

2 var app = Application. currentApplication() 
3 app.includeStandardAdditions = true 

4 app.displayDialog("The script is running.") 
5 + 


Quit Handlers 


The quit event handler is optional, and is called when a script app quits. Use this as an opportunity to perform 
cleanup tasks, if necessary, such as removing temporary folders or logging progress. Listing 13-21 and Listing 
13-22 demonstrate the use of a quit handler. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-21 AppleScript: Example of a quit handler 


1 on quit 
2 display dialog "The script is quitting." 
3 end quit 


JAVASCRIPT 
Open in Script Editor 
Listing 13-22 JavaScript: Example of a quit function 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


1 

2 

3 

4 function quit() { 
5 app.displayDialog("The script is quitting.") 
6 

Open Handlers 


The inclusion of an open handler or openDocuments method in a script app automatically makes the app drag- 
and-droppable. When launched in this way, the open handler receives a dropped list of files or folders as a 
direct parameter, as shown in Listing 13-23 and Listing 13-24. 


APPLESCRIPT 
Open in Script Editor 
Listing 13-23 AppleScript: Structure of an open handler 


1 on open theDroppedItems 
2 -- Process the dropped items here 


3 end open 


JAVASCRIPT 
Open in Script Editor 
Listing 13-24 JavaScript: Structure of an openDocuments function 


1 function openDocuments(droppediItems) { 


2 // Process the dropped items here 


For detailed information about using the open handler to create drop scripts, see Processing Dropped Files 
and Folders. 


Idle Handlers 


When saving a script, you can optionally save it as a stay-open application. See Figure 13-1. In a stay-open 
script app, the script stays open after the run handler completes, and an idle handler is called every 30 
seconds. Use the idle handler to perform periodic processing tasks, such as checking a watched folder for 
new files to process. To change the duration between idle calls, return a new duration, in seconds, as the 
result of the idle handler. Listing 13-25 and Listing 13-26 demonstrate an idle handler that delays for five 
seconds between executions. 


Figure 13-1 Saving a stay-open script 


Export As: My Stay Opened Script v 


Tags: 
Where: | Desktop 
File Format: Application 
Options: Show startup screen 
Stay open after run handler 
Run-only 
Code Sign: Don’t Code Sign 


APPLESCRIPT 
Open in Script Editor 


Listing 13-25 AppleScript: Example of an idle handler 


1 on idle 

2 display dialog "The script is idling." 
3 return 5 

4 end idle 

JAVASCRIPT 


Open in Script Editor 
Listing 13-26 JavaScript: Example of an idle function 


var app = Application.currentApplication() 


app.includeStandardAdditions = true 


app.displayDialog("The script is idling.") 


1 

2 

3 

4 function idle() { 
5 

6 return 5 
7 


For information about using the idle handler for folder watching, see Watching Folders. 
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Using Script Libraries 


A script library is a collection of handlers, which can be loaded and used by other scripts. For example, a 
scripter might compile a set of commonly-used text-processing handlers into a text library. This library could 
then be shared by multiple scripts that need to perform text processing operations. 


Writing Script Libraries 


To write a script library, create a Script Editor document that contains one or more handlers, such as the one 
shown in Listing 14-1 and Listing 14-2, and save it in script format, as shown in Figure 14-1. 


Figure 14-1 Saving a script library 


Save As: My Text Processo} v 


Tags: 
Where: | Desktop 
File Format: Script 


Options: Show startup screen 
Stay open after run handler 


APPLESCRIPT 
Open in Script Editor 


Listing 14-1 AppleScript: Handler that converts text to uppercase or lowercase 


1 on changeCaseOfText(theText, theCaseToSwitchTo) 
2 if theCaseToSwitchTo contains "lower" then 
3 set theComparisonCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
4 set theSourceCharacters to “abcdefghijklmnopqrstuvwxyz" 
5 else if theCaseToSwitchTo contains "upper" then 
6 set theComparisonCharacters to "abcdefghijklmnopqrstuvwxyz" 
7 set theSourceCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
8 else 
9 return theText 
10 end if 
iE set theAlteredText to "" 
12 repeat with aCharacter in theText 
13 set theOffset to offset of aCharacter in theComparisonCharacters 
14 if theOffset is not @ then 
15 set theAlteredText to (theAlteredText & character theOffset of 


theSourceCharacters) as string 


16 else 

17 set theAlteredText to (theAlteredText & aCharacter) as string 
18 end if 

19 end repeat 

20 return theAlteredText 


21 end changeCaseOfText 


JAVASCRIPT 


Open in Script Editor 


Listing 14-2 JavaScript: Function that converts text to uppercase or lowercase 


function changeCaseOfText(text, caseToSwitchTo) { 
var alteredText = text 
if (caseToSwitchTo === "lower") { 


alteredText = alteredText.toLowerCase() 


else if (caseToSwitchTo === "upper") { 
alteredText = alteredText.toUpperCase() 
t 


1 
2 
3 
4 
5 } 
6 
7 
8 
9 return alteredText 


10 + 


Move the saved script to one of the following folders on your Mac, creating the folder if it doesn’t already exist: 


¢ «/Library/Script Libraries/ 
« /Library/Script Libraries/ 


* /Resources/ folder inside a script or app bundle. 


For additional information about writing script libraries, see Creating a Library in AppleScript Language Guide 
and Libraries in JavaScript for Automation Release Notes. 


Using Script Libraries 

Once a script library is installed, your other scripts can target its handlers at any time. 
To target a script library in AppleScript, use a tell statement, as shown in Listing 14-3. 
APPLESCRIPT 

Open in Script Editor 

Listing 14-3 AppleScript: Targeting a handler in a script library 


1 tell script "My Text Processor" 

2 changeCaseOfText("scripting is awesome!", "“upper") 
3 end tell 

4 --> Result: "SCRIPTING IS AWESOME!" 


To target a script library in JavaScript, use the Library command to reference the library. Then, you can target 
handlers in the referenced library, as shown in Listing 14-4. 


JAVASCRIPT 
Open in Script Editor 
Listing 14-4 JavaScript: Targeting a function in a script library 


1 textProcessor = Library("My Text Processor") 
2 textProcessor.changeCaseOfText("scripting is awesome!", "“upper") 


2 // Result: "SCRIPTING IS AWESOME!" 
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Referencing Files and Folders 


Referencing Files and Folders in AppleScript 


In AppleScript, file and folder paths are typically represented using alias, file, and POSIX file objects. 


NOTE 


Additional information about working with file and folder paths in AppleScript can be found in Aliases and 
Files in AppleScript Language Guide. 


Alias Objects 


An alias object dynamically points to an existing item in the file system. Since an alias is dynamic, it 
continues pointing to the item even if the item is renamed or moved, the same way an alias file works when 
you manually create one in the Finder. With an AppleScript alias, the original item must exist at run time or an 
error will occur. 


An alias object is displayed as a colon-delimited path preceded by an alias specifier, in the format shown in 
Listing 15-1. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-1 AppleScript: Structure of an alias object 


alias "VolumeName: FolderName: SubfolderName: FileName" 


Listing 15-2 shows an example of an alias object that references the Desktop folder. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-2 AppleScript: Example of an alias reference to a folder 


alias "Macintosh HD:Users: yourUserName:Desktop:" 


Listing 15-3 is an example of an alias object that references an existing file on the Desktop. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-3 AppleScript: Example of an alias reference to a file 


alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


To create an alias, add the alias specifier prefix to a colon-delimited path string, as shown in Listing 15-4. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-4 AppleScript: Creating an alias from a colon-delimited path string 


set thePath to alias "Macintosh HD:Users: yourUserName:Desktop:" 


Many commands accept an alias as a parameter and/or return an alias as a result. In Listing 15-5, the choose 
file command accepts a folder alias object inits default location parameter. The command then returns 
an alias object that points to the chosen file. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-5 AppleScript: Example of a command that accepts an alias parameter and returns an alias result 


1 set theDefaultFolder to alias "Macintosh HD:Users:yourUserName:Desktop:" 


2 choose file default location theDefaultFolder 


3 --> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


File Objects 


A file object is a static reference to an item at a specific location in the file system. It’s not dynamic, and can 
even refer to an item that doesn’t exist yet. For example, a save command may accept a file reference when 
saving to a new file. 


A file object is displayed as a colon-delimited path preceded by a file specifier, in the format shown in 
Listing 15-6. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-6 AppleScript: Structure of a file object 


file "VolumeName: FolderName: SubfolderName: FileName" 


Listing 15-7 shows an example of a file object that references a file that may or may not exist on the 
Desktop. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-7 AppleScript: Example of a file reference to a file 


file "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


Unlike the way an alias object works, you can’t create a file object simply by prefixing a path string with the 
file specifier. For example, Listing 15-7 errors when run within a script. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-8 AppleScript: Example of incorrect usage of a file object specifier 


set theFile to file "Macintosh HD:Users:yourUserName:Desktop:My File. txt" 


Instead, you must prefix the path with the file specifier at the time the file is targeted by a command, as 
shown in Listing 15-8. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-9 AppleScript: Example of correct usage of a file object specifier 


1 set theFile to "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 
2 read file theFile 


NOTE 


A file object can refer to either a file or a folder, despite the file specifier prefix. 


POSIX File Objects 


Some scriptable apps are designed to work with POSIX-style paths, rather than AppleScript alias and file 
objects. Like a file object, a POSIX file object is not dynamic and can also refer to an item that doesn’t exist 
yet. 


A POSIX file object is displayed as a slash-delimited path preceded by a POSIX file specifier, in the format 
shown in Listing 15-10. 


APPLESCRIPT 


Open in Script Editor 


Listing 15-10 AppleScript: Structure of a POSIX file object 


POSIX file "/FolderName/SubfolderName/FileName" 


Listing 15-11 is an example of a POSIX file object that references a file that may or may not exist on the 
Desktop. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-11 AppleScript: Example of a POSIX file reference to a file 


POSIX file "/Users/yourUserName/Desktop/My File.txt" 


NOTE 


A POSIX file object can refer to either a file or a folder, despite the POSIX file specifier prefix. 


In a POSIX path, the startup disk’s name is omitted and represented by a leading slash. Other disks are 
referenced in relation to the Volumes directory of the startup disk, for example: 
/Volumes/DiskName/FolderName/SubFo lderName/FileName. 


App-Specific References to Files and Folders 


Some apps, such as the Finder and System Events, have their own syntax for referring to files and folders. 
Listing 15-12 shows how a Finder file reference appears. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-12 AppleScript: Example of a reference to a file in the Finder 


document file "My File.txt" of folder "Desktop" of folder "yourUserName" of folder 


"Users" of startup disk of application "Finder" 


Listing 15-13 shows how a System Events folder reference appears. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-13 AppleScript: Example of a reference to a folder in System Events 


folder "Macintosh HD:Users:yourUserName:Desktop:" of application "System Events" 


Since this terminology is app-specific, it doesn’t work in other apps. For example, you can’t write a script that 
tries to import a Finder reference to an audio file into iTunes because iTunes doesn’t understand Finder file 
references. In this case, you must coerce the Finder file reference to something iTunes can understand, like 
an alias. See Converting Between Path Formats below. In most cases, apps with their own path syntax also 
support standard AppleScript path types. 


Converting Between Path Formats 


Since different situations may result in paths appearing in different formats, you may need to regularly convert 
one path format to another. Sometimes, this can be done by using the as coercion operator, as shown in 
Listing 15-14, Listing 15-15, Listing 15-16, and Listing 15-17. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-14 AppleScript: Coercing a string to an alias 


1 set theFilePath to "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 
2 set theFilePath to theFilePath as alias 


3 --> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


APPLESCRIPT 


Open in Script Editor 
Listing 15-15 AppleScript: Coercing an alias to a string 
set theFilePath to choose file 


--> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


set theFilePath to theFilePath as string 


un B WN FR 


--> Result: "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


APPLESCRIPT 
Open in Script Editor 
Listing 15-16 AppleScript: Coercing a POSIX file to an alias 


1 set theFilePath to POSIX file "/Users/yourUserName/Desktop/My File.txt" 
2 set theFilePath to theFilePath as alias 
3 --> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


APPLESCRIPT 
Open in Script Editor 
Listing 15-17 AppleScript: Coercing a Finder file reference to an alias 


1 tell application "Finder" 

2 set theFilePath to file "My File.txt" of desktop 

3 end tell 

4 --> Result: document file "My File.txt" of folder "Desktop" of folder "yourUserName" 


of folder "Users" of startup disk of application "Finder" 


ul 


6 set theFilePath to theFilePath as alias 


7 --> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


Converting from a string or alias to a POSIX path can’t be done through coercion. Instead, you must access 
the POSIX path property of the path to convert, as shown in Listing 15-18. 


APPLESCRIPT 

Open in Script Editor 

Listing 15-18 AppleScript: Converting an alias to a POSIX path string 
set theFilePath to choose file 


--> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


set theFilePath to POSIX path of theFilePath 


wu BW NY RP 


--> Result: "/Users/yourUserName/Desktop/My File.txt" 


Using Conversion Handlers 


Running paths through a conversion handler is a good way to ensure the format you expect. 


Converting a Path to an Aliases 


The handler in Listing 15-19 converts strings, path objects, POSIX file objects, Finder paths, and System 
Events paths to alias format. 


APPLESCRIPT 
Open in Script Editor 
Listing 15-19 AppleScript: Handler that converts a path to an AppleScript alias 


1 on convertPathToAlias(thePath) 

2 tell application "System Events" 
3 try 
4 


return (path of disk item (thePath as string)) as alias 


on error 


return (path of disk item (path of thePath) as string) as alias 


5 
6 
7 end try 
8 end tell 
9 


end convertPathToAlias 


Listing 15-19 shows how to call the handler in Listing 15-19 to convert a POSIX-style path string to an alias. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-20 AppleScript: Calling a handler to convert a path to an AppleScript alias 


1 set thePath to "/Users/yourUserName/Desktop/My File.txt" 
2 set thePath to convertPathToAlias(thePath) 


3 --> Result: alias "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


Converting a Path to a String 

The handler in Listing 15-21 converts a path to string format. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-21 AppleScript: Handler that converts a path to an a string 


on convertPathToString(thePath) 
tell application "System Events" 
try 
return path of disk item (thePath as string) 


return path of thePath 
end try 


1 

2 

3 

4 

5 on error 
6 

7 

8 end tell 
9 


end convertPathToString 


Listing 15-22 shows how to call the handler in Listing 15-21 to convert an alias to a path string. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-22 AppleScript: Calling a handler to convert an AppleScript alias to a path string 


1 set thePath to alias "Macintosh HD:Users: yourUserName:Desktop:My File.txt" 
2 set thePath to convertPathToString(thePath) 
3 --> Result: "Macintosh HD:Users:yourUserName:Desktop:My File.txt" 


Converting a Path to a POSIX Path String 

The handler in Listing 15-23 converts a path to POSIX path string format. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-23 AppleScript: Handler that converts a path to an a POSIX path string 


on convertPathToPOSIXString(thePath) 
tell application "System Events" 
try 
set thePath to path of disk item (thePath as string) 


set thePath to path of thePath 
end try 


A 

2 

3 

4 

5 on error 
6 

7 

8 end tell 
9 


return POSIX path of thePath 


10 end convertPathToPOSIXString 


Listing 15-24 shows how to call the handler in Listing 15-23 to convert an alias to a path string. 
APPLESCRIPT 

Open in Script Editor 

Listing 15-24 AppleScript: Calling a handler to convert an AppleScript alias to a POSIX path string 


1 set thePath to alias "Macintosh HD:Users: yourUserName:Desktop:My File.txt" 
2 set thePath to convertPathToPOSIXString(thePath) 
3 --> Result: "/Users/yourUserName/Desktop/My File. txt" 


Referencing Files and Folders in JavaScript 

In JavaScript, file and folder paths are represented using Path objects. 

To create a path, pass a POSIX-style string to the Path object, as shown in Listing 15-25. 
JAVASCRIPT 

Listing 15-25 JavaScript: Creating a Path object 


Path("/FolderName/SubfolderName/FileName" ) 


To convert a path to a string, call the toString() method on the path, as shown in Listing 15-26. 
JAVASCRIPT 

Open in Script Editor 

Listing 15-26 JavaScript: Converting a Path object to a string 


1 var path = Path("/Users/yourUserName/Desktop/My File.txt") 
2 var string = path.toString() 

3 string 

4 // Result: "/Users/yourUserName/Desktop/My File.txt" 
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Reading and Writing Files 


Scripts are often designed to write data to files such as logs or backups. The Standard Additions scripting 
addition contains a number of commands that make it possible to read and write files. 


Writing to a File 


The handlers in Listing 16-1 and Listing 16-2 safely write data to disk, creating a new file if the targeted file 
doesn’t already exist. Provide the text to write, a target file path, and indicate whether to overwrite existing 
content. If you choose not to overwrite existing content, then the text provided is appended to any existing 


content. 


APPLESCRIPT 


Open in Script Editor 


Listing 16-1 AppleScript: Handler that writes text to a file 





1 on writeTextToFile(theText, theFile, overwriteExistingContent) 
2 try 
3 
4 -- Convert the file to a string 
5 set theFile to theFile as string 
6 
7 -- Open the file for writing 
8 set theOpenedFile to open for access file theFile with write permission 
9 
10 -- Clear the file if content should be overwritten 
11 if overwriteExistingContent is true then set eof of theOpenedFile to 0 
12 
13 -- Write the new content to the file 
14 write theText to theOpenedFile starting at eof 
15 
16 == Close the file 
17 close access theOpenedFile 
18 
19 -- Return a boolean indicating that writing was successful 
20 return true 
21 
22 -- Handle a write error 
23 on error 
24 
25 == Close the file 
26 try 
27 close access file theFile 
28 end try 
29 
30 -- Return a boolean indicating that writing failed 
31 return false 
32 end try 


33 end writeTextToFile 


JAVASCRIPT 


Open in Script Editor 


Listing 16-2 JavaScript: Function that writes text to a file 


1 var app 


= Application. currentApplication() 


2 app.includeStandardAdditions = true 





4 function writeTextToFile(text, file, overwriteExistingContent) { 
5 try { 
6 
7 // Convert the file to a string 
8 var fileString = file.toString() 
9 
10 // Open the file for writing 
11 var openedFile = app.openForAccess(Path(fileString), { writePermission: true 
}) 
12 
13 // Clear the file if content should be overwritten 
14 if (overwriteExistingContent) { 
15 app.setEof(openedFile, { to: @ }) 
16 t 
17 
18 // Write the new content to the file 
19 app.write(text, { to: openedFile, startingAt: app.getEof(openedFile) }) 
20 
21 // Close the file 
22 app.closeAccess (openedFile) 
23 
24 // Return a boolean indicating that writing was successful 
25 return true 
26 + 
27 catch(error) { 
28 
29 try { 
30 // Close the file 
31 app.closeAccess (file) 
32 t 
33 catch(error) { 
34 // Report the error is closing failed 
35 console. log(*Couldn't close file: ${error}* ) 
36 } 
37 
38 // Return a boolean indicating that writing was successful 
39 return false 
40 + 
41 + 


Listing 16-3 and Listing 16-4 show how to call the handlers in Listing 16-1 and Listing 16-2 to write text content 
to a file on the Desktop, replacing any existing content in the file. 


APPLESCRIPT 
Open in Script Editor 
Listing 16-3 AppleScript: Calling a handler to write text to a file 


1 set this_story to "Once upon a time in Silicon Valley..." 
2 set theFile to (((path to desktop folder) as string) & "MY STORY.txt") 
3 writeTextToFile(this_story, theFile, true) 


JAVASCRIPT 
Open in Script Editor 
Listing 16-4 JavaScript: Calling a function to write text to a file 


var story = "Once upon a time in Silicon Valley..." 
var desktopString = app.pathTo("desktop").toString() 
var file = *${desktopString}/MY STORY.txt> 


writeTextToFile(story, file, true) 
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Listing 16-5 and Listing 16-6 show how Listing 16-1 and Listing 16-2 could be called to insert dated log entries 
into a log file. 


APPLESCRIPT 
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Listing 16-5 AppleScript: Calling a handler to write an entry to a log file 


1 set theText to ((current date) as string) & space & "STATUS OK" & return 
2 set theFile to (((path to desktop folder) as string) & "MY LOG FILE. log") 
3 writeTextToFile(theText, theFile, false) 


JAVASCRIPT 
Open in Script Editor 
Listing 16-6 JavaScript: Calling a function to write an entry to a log file 


var dateString = Date().toString() 

var desktopString = app.pathTo("desktop").toString() 
var text = ‘${dateString} STATUS OK\n\n°~ 

var file = ‘${desktopString}/MY LOG FILE. log° 
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writeTextToFile(text, file, false) 


In practice, this technique could be used to maintain a log when script errors occur. Listing 16-7 and Listing 
16-8 are try statements, which can be wrapped around custom script code in order to log any script errors to a 
file in the ~/Library/Logs/ folder of the current user’s home directory. 


APPLESCRIPT 


Open in Script Editor 


Listing 16-7 AppleScript: Example of a try statement that writes an entry to a log file when an error occurs 


1 try 

2 -- Your custom script code goes here 

3 on error theErrorMessage number theErrorNumber 

4 set theError to "Error: " & theErrorNumber & '". " & theErrorMessage & return 

5 set theLogFile to ((path to library folder from user domain) as string) & 
"Logs:Script Error Log. log" 

6 my writeTextToFile(theError, theLogFile, false) 

7 end try 

JAVASCRIPT 
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Listing 16-8 JavaScript: Example of a try statement that writes an entry to a log file when an error occurs 


1 try { 

2 // Your custom script code goes here 

3 4} 

4 catch (error) { 

5 var errorString = ‘Error: ${error.message}\n\n~ 

6 var logFile = app.pathTo("library folder", { from: "user domain" }).toString() + 
"/Logs/Script Error Log. log" 

7 writeTextToFile(errorString, logFile, false) 

8 4} 

Reading a File 


The handlers in Listing 16-9 and Listing 16-10 read the contents of a specified file. 
APPLESCRIPT 
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Listing 16-9 AppleScript: Handler that reads the contents of a file 


1 on readFile(theFile) 

2 -- Convert the file to a string 

3 set theFile to theFile as string 

4 

5 -- Read the file and return its contents 
6 return read file theFile 

7 end readFile 

JAVASCRIPT 
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Listing 16-10 JavaScript: Function that reads the contents of a file 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 function readFile(file) { 

5 // Convert the file to a string 

6 var fileString = file.toString() 

7 

8 // Read the file and return its contents 
9 return app. read(Path(fileString) ) 

10 + 


Listing 16-11 and Listing 16-12 show how to call the handlers in Listing 16-9 and Listing 16-10 to read a 
specified text file. 


APPLESCRIPT 
Open in Script Editor 
Listing 16-11 AppleScript: Calling a handler to read the contents of a file 


1 set theFile to choose file of type "txt" with prompt "Please select a text file to 


read:" 
2 readFile(theFile) 


3 --> Result: "Contents of the chosen file." 
JAVASCRIPT 
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Listing 16-12 JavaScript: Calling a function to read the contents of a file 


1 var file = app.chooseFile({ 

2 ofType: "txt", 

3 withPrompt: "Please select a text file to read:" 
4 }) 

5 

6 readFile(file) 

7 


// Result: "Contents of the chosen file." 


Reading and Splitting a File 


The handlers in Listing 16-13 and Listing 16-14 read the contents of a specified text file, using a delimiter to 
split it into a list. 


APPLESCRIPT 
Open in Script Editor 
Listing 16-13 AppleScript: Handler for reading and splitting the contents of a file based on a delimiter 


on readAndSplitFile(theFile, theDelimiter) 
-- Convert the file to a string 


a 
2 
3 set theFile to theFile as string 
4 


5 -- Read the file using a specific delimiter and return the results 
6 return read file theFile using delimiter {theDelimiter} 


7 end readAndSplitFile 


JAVASCRIPT 
Open in Script Editor 


Listing 16-14 JavaScript: Function for reading and splitting the contents of a file based on a delimiter 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 function readAndSplitFile(file, delimiter) { 

5 // Convert the file to a string 

6 var fileString = file.toString() 

7 

8 // Read the file using a specific delimiter and return the results 
9 return app.read(Path(fileString), { usingDelimiter: delimiter }) 
10 + 


Listing 16-15 and Listing 16-16 shows how to call the handlers in Listing 16-13 and Listing 16-14 to read the 
paragraphs of a chosen log file. 


APPLESCRIPT 
Open in Script Editor 
Listing 16-15 AppleScript: Calling a handler to read and split the contents of a file based on a delimiter 


1 set theFile to choose file of type "log" with prompt "Please select a log file:" 
2 readAndSplitFile(theFile, return) 
3 --> Result: {"Log entry 1", "Log entry 2", ... } 


JAVASCRIPT 
Open in Script Editor 
Listing 16-16 JavaScript: Calling a function to read and split the contents of a file based on a delimiter 


var file = app.chooseFile({ 


ofType: "log", 


1 

2 

3 withPrompt: "Please select a log file: 
4 }) 

5 readAndSplitFile(file, "\n") 

6 // Result: ["Log entry 1", "Log entry 2", ...] 
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Processing Dropped Files and Folders 


Droplets are applets configured to process dropped files and folders. A droplet is distinguishable from a 
normal applet because its icon includes a downward pointing arrow, as shown in Figure 17-1. 


Figure 17-1 A script droplet icon 


To create an AppleScript droplet, include an open event handler in your script and save the script as an 
application. To create a JavaScript droplet, include an openDocuments function in your script and save the 
script as an application. The presence of this handler or function automatically renders the saved application 
as a droplet, allowing it to accept dropped files and folders in the Finder. The open handler and openDocuments 
function accept a single parameter—a list of dropped files or folders—which are passed to the handler when 
the script is activated by dropping something onto it. In AppleScript, these dropped files and folders are alias 
objects. In JavaScript, they’re Path objects. For more information about these types of objects, see 
Referencing Files and Folders. 


An AppleScript open handler is formatted as shown in Listing 17-1. 
APPLESCRIPT 

Open in Script Editor 

Listing 17-1 AppleScript: Structure of an open handler 


1 on open theDroppedItems 
2 -- Process the dropped items here 


3 end open 


A JavaScript openDocuments function is formatted as shown in Listing 17-2. 
JAVASCRIPT 

Open in Script Editor 

Listing 17-2 JavaScript: Structure of an openDocuments function 


1 function openDocuments(droppedItems) { 
2 // Process the dropped items here 


3 } 


Typically, a droplet loops through items dropped onto it, processing them individually, as in Listing 17-3 and 
Listing 17-4. 


APPLESCRIPT 
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Listing 17-3 AppleScript: An open handler that loops through dropped items 


1 on open theDroppedItems 

2 repeat with a from 1 to length of theDroppedItems 

3 set theCurrentDroppedItem to item a of theDroppedItems 
4 -- Process each dropped item here 

5 end repeat 

6 end open 

JAVASCRIPT 


Open in Script Editor 


Listing 17-4 JavaScript: An openDocuments function that loops through dropped items 


1 function openDocuments(droppediItems) { 

2 for (var item of droppedItems) { 

3 // Process each dropped item here 
4 } 

5 } 


To run a droplet, drop files or folders onto it in the Finder. To test a droplet in Script Editor, add the following 
line(s) of code to the root level—the run handler portion—of the script. Listing 17-5 and Listing 17-6 prompt 
you to select a file and then passes it to the open handler or openDocuments function. 


APPLESCRIPT 
Open in Script Editor 
Listing 17-5 AppleScript: Calling the open handler to test a droplet within Script Editor 


open {choose file} 


JAVASCRIPT 
Open in Script Editor 
Listing 17-6 JavaScript: Calling the openDocuments handler to test a droplet within Script Editor 


1 var app = Application. currentApplication() 
2 app. includeStandardAdditions = true 

3 var file = app.chooseFile() 
4 


openDocuments( [file] ) 


Creating an AppleScript Droplet from a Script Editor Template 


Script Editor includes several preconfigured AppleScript droplet templates, which solve the majority of droplet 
use Cases. 


NOTE 


Script Editor does not include JavaScript templates at this time. 


To create a droplet from a Script Editor template 
1. Launch Script Editor from /Applications/Utilities/. 
2. Select File > New from Template > Droplets. 
3. Choose a droplet template. 
Options include: 


e Droplet with Settable Properties—This template processes dropped files based on file type, 
extension, or type identifier. It also demonstrates how to include a user-configurable setting, 
which affects the behavior of the script. 


e Recursive File Processing Droplet—This template processes dropped files based on file type, 
extension, or type identifier. It is configured to detect files within dropped folders and their 
subfolders. 


e Recursive Image File Processing Droplet—This template processes image files matching 
specific file types, extensions, or type identifiers. It is configured to detect images within dropped 
folders and their subfolders. 


All of these templates are designed to serve as starting points for creating a droplet, and can be 
customized, as needed. 


Creating a Droplet to Process Files 


In Listing 17-7 and Listing 17-8, the open handler and openDocuments function process dropped files based on 
file type, extension, or type identifier. The file types, extensions, and type identifiers supported by the handler 
are configurable in properties at the top of the script. If a dropped file matches the criteria you configure, then 


the file is passed to the processItem() handler, where you can add custom file processing code. These 
examples are not configured to process dropped folders. 


APPLESCRIPT 
Open in Script Editor 
Listing 17-7 Handler that processes dropped files matching specific file types, extensions, or type identifiers 


1 property theFileTypesToProcess : {} -- For example: {"PICT", "JPEG", "TIFF", "GIFf"} 


2 property theExtensionsToProcess : {} -- For example: {"txt", "text", "jpg", "jpeg"}, 
NOT: {".txt", ".text", ".jpg", ".jpeg"} 
3 property theTypeIdentifiersToProcess : {} -- For example: {"public. jpeg", 
“public.tiff", "public.png"} 
4 
5 on open theDroppedItems 
6 repeat with a from 1 to count of theDroppedItems 
7 set theCurrentItem to item a of theDroppedItems 
8 tell application "System Events" 
9 set theExtension to name extension of theCurrentItem 
10 set theFileType to file type of theCurrentItem 
11 set theTypeIdentifier to type identifier of theCurrentItem 
12 end tell 
13 if ((theFileTypesToProcess contains theFileType) or (theExtensionsToProcess 
contains theExtension) or (theTypeIdentifiersToProcess contains 
theTypeIdentifier)) then 
14 processItem(theCurrentItem) 
15 end if 
16 end repeat 
17 end open 
18 
19 on processItem(theItem) 
20 -- NOTE: The variable theItem is a file reference in AppleScript alias format 


21 -- Add item processing code here 


22 end processItem 


JAVASCRIPT 
Open in Script Editor 
Listing 17-8 Function that processes dropped files matching specific file types, extensions, or type identifiers 


1 var SystemEvents = Application("System Events") 
2 var fileTypesToProcess = [] // For example: {"PICT", "JPEG", "TIFF", "GIFf"} 


3 var extensionsToProcess = [] // For example: {"txt", "text", "jpg", "jpeg"}, NOT: 
{".txt", "Jtext", ™.7p0"; ",jpeg"} 
4 var typeIdentifiersToProcess = [] // For example: {"public.jpeg", "public.tiff", 


"public.png"} 


function openDocuments(droppedItems) { 
for (var item of droppedItems) { 
var alias = SystemEvents.aliases.byName(item.toString() ) 


var extension = alias.nameExtension() 


y 


var fileType = alias. fileType() 


y 


var typeIdentifier = alias.typeIdentifier() 
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ry 


if (fileTypesToProcess.includes(fileType) | 


extensionsToProcess.includes(extension) | | 
typeIdentifiersToProcess.includes(typeIdentifier)) { 


processItem(item) 





function processItem(item) { 


19 // NOTE: The variable item is an instance of the Path object 
20 // Add item processing code here 


Creating a Droplet to Process Files and Folders 


In Listing 17-9 and Listing 17-10, the open handler and openDocuments function loop through any dropped files 
and folders. 


For each dropped file, the script calls the processFile() handler, which determines whether the file matches 
specific file types, extensions, and type identifiers. The file types, extensions, and type identifiers supported by 
the handler are configurable in properties at the top of the script. If there’s a match, then any custom file 
processing code you add runs. 


The script passes each dropped folder to the processFolder(), which retrieves a list of files and subfolders 
within the dropped folder. The processFolder() handler recursively calls itself to process any additional 
subfolders. It calls the processFile() handler to process any detected files. If necessary, you can add custom 
folder processing code to the processFolder() handler. 


APPLESCRIPT 
Open in Script Editor 
Listing 17-9 Handler that processes dropped folders and files 


1 property theFileTypesToProcess : {} -- I.e. {"PICT", "JPEG", "TIFF", "GIFf"} 

2 property theExtensionsToProcess : {} -- I.e. {"txt", "text", "jpg", "jpeg"}, NOT: 
{", txt", “text, “.jpg", ".Tpeg"} 

3 property theTypeIdentifiersToProcess : {} -- I.e. {"public.jpeg", "“public.tiff", 
"public. png"} 


4 
5 on open theDroppedItems 
6 repeat with a from 1 to count of theDroppedItems 
7 set theCurrentItem to item a of theDroppedItems 
8 tell application "Finder" 
9 set isFolder to folder (theCurrentItem as string) exists 
10 end tell 
11 
12 -- Process a dropped folder 
13 if isFolder = true then 
14 processFolder(theCurrentItem) 
15 
16 -- Process a dropped file 
17 else 
18 processFile(theCurrentItem) 
19 end if 
20 end repeat 


21 end open 


22 

23 on processFolder(theFolder) 

24 -- NOTE: The variable theFolder is a folder reference in AppleScript alias 
format 

25 -- Retrieve a list of any visible items in the folder 

26 set theFolderItems to list folder theFolder without invisibles 

27 

28 -- Loop through the visible folder items 

29 repeat with a from 1 to count of theFolderItems 

30 set theCurrentItem to ((theFolder as string) & (item a of theFolderItems) ) 
as alias 

31 open {theCurrentItem} 

32 end repeat 

33 -- Add additional folder processing code here 


34 end processFolder 





36 on processFile(theItem) 

37 -- NOTE: variable theItem is a file reference in AppleScript alias format 

38 tell application "System Events" 

39 set theExtension to name extension of theItem 

40 set theFileType to file type of theItem 

41 set theTypeIdentifier to type identifier of theItem 

42 end tell 

43 if ((theFileTypesToProcess contains theFileType) or (theExtensionsToProcess 
contains theExtension) or (theTypeIdentifiersToProcess contains 
theTypeIdentifier)) then 

44 -- Add file processing code here 

45 display dialog theItem as string 

46 end if 

47 end processFile 

JAVASCRIPT 
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Listing 17-10 Function that processes dropped folders and files 


ue 
2 
3 
4 
5 
6 
7 





var SystemEvents = Application("System Events") 
var fileManager = $.NSFileManager.defaultManager 
var currentApp = Application. currentApplication() 


currentApp. includeStandardAdditions = true 


var fileTypesToProcess = [] // For example: {"PICT", "JPEG", "TIFF", "GIFf"} 


var extensionsToProcess = [] // For example: {"txt", "text", "jpg", "jpeg"}, NOT: 
Ext ",text", “5 7po", ",jpeg"} 
var typeIdentifiersToProcess = [] // For example: {"public.jpeg", "public.tiff", 


"public. png"} 


function openDocuments(droppediItems) { 
for (var item of droppedItems) { 
var isDir = Ref() 
if (fileManager.fileExistsAtPathIsDirectory(item.toString(), isDir) && 
isDir[0]) { 


processFolder( item) 


} 

else { 
processFile(item) 

} 


function processFolder(folder) { 
// NOTE: The variable folder is an instance of the Path object 


var folderString = folder.toString() 


// Retrieve a list of any visible items in the folder 


var folderItems = currentApp.listFolder(folder, { invisibles: false }) 


// Loop through the visible folder items 

for (var item of folderItems) { 
var currentItem = ‘${folderString}/${item}° 
openDocuments( [currentItem] ) 

+ 


// Add additional folder processing code here 


function processFile(file) { 


// NOTE: The variable file is an instance of the Path object 


var fileString = file.toString() 

var alias = SystemEvents.aliases. byName(fileString) 
var extension = alias.nameExtension() 

var fileType = alias. fileType() 

var typeIdentifier = alias. typeIdentifier() 


if (fileTypesToProcess.includes(fileType) || 


extensionsToProcess.includes(extension) | | 


typeIdentifiersToProcess.includes(typeIdentifier)) { 


// Add file processing code here 
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Watching Folders 


The ability to watch folders and take action on incoming items is a powerful automation technique that enables 
the creation of fully unattended workflows. A watched folder might be used, for example, to watermark 
incoming photos, convert them to PDF, and email them to clients for review. Many companies set up script 
servers—dedicated robot machines that watch folders and process detected items, allowing employees to 
offload tedious and repetitious work in order to focus on other important tasks. 


In OS X, there are two primary ways to set up scripting-based watched folders: folder actions and stay open 
script apps. 


Using Folder Actions to Watch Folders 


Folder actions is a feature in OS X that lets you connect scripts to folders on your Mac. A folder action script 
includes one or more event handlers that run in response to certain events, such as opening, closing, or 
adding items to the connected folder. With folder actions, you can create automated workflows that: 


« Notify you when new files and folders arrive in a folder 

¢ Notify you when existing files and folders are removed from a folder 
- Perform processing of newly detected files and folders 

+ Initiate any automated task when a new file or folder is detected 


+ Adjust or reset the view properties of a folder’s window when it’s opened, closed, or resized 


Write a Folder Action Script 


The event handlers supported by folder actions are defined in the Standard Additions scripting addition that 
comes with OS X. They are: 


Folder event Event handler Parameters 


+ Direct parameter—The 


: , . connected folder. 
Items—files or folders—are adding folder items 


added to the folder to after receiving—A list of 
items added to the folder. 


Direct parameter—The 
connected folder. 


after losing—A list of 


removing folder items removed from the 


Items are removed from the folder oer ere folder. For items that were 


deleted, names of the 
removed items are 
provided. 


Direct parameter—The 


The folder is opened in a new 
P opening folder connected folder. 


Finder window 


closing folder Direct parameter—The 


The window of a folder is closed ; connected folder. 
window for 


Direct parameter—The 
connected folder. 


moving folder window 


from—The coordinates of 
the folder’s window before it 
was moved. 


The window of a folder is moved for 


To create a folder action script 


1. Create a Script Editor document. 
2. Add one or more folder action event handlers to the document. 
3. Save the document as a compiled script to one of the following folders: 


e /Library/Scripts/Folder Action Scripts/—The script can be used by any user. 

e ~/Library/Scripts/Folder Action Scripts/—The script can be used by the current user only. 
The following examples demonstrate how to use different folder action event handlers. 
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Listing 18-1 AppleScript: Example of the opening folder event handler 


1 on opening folder theAttachedFolder 

2 -- Get the name of the attached folder 

3 tell application "Finder" 

4 set theName to name of theAttachedFolder 

5 

6 -- Display an alert indicating that the folder was opened 

7 activate 

8 display alert "Attention!" message "The folder " & (quoted form of theName) 


& " was opened." 
9 end tell 
10 end opening folder 


APPLESCRIPT 
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Listing 18-2 AppleScript: Example of the closing folder window for event handler 


1 on closing folder window for theAttachedFolder 

2 -- Get the name of the attached folder 

3 tell application "Finder" 

4 set theName to name of theAttachedFolder 

5 

6 -- Display an alert indicating that the folder was closed 

7 activate 

8 display alert "Attention!" message "The folder " & (quoted form of theName) 
& " was closed." 

9 end tell 


10 end closing folder window for 


APPLESCRIPT 
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Listing 18-3 AppleScript: Example of the adding folder items to event handler 


1 on adding folder items to theAttachedFolder after receiving theNewItems 
2 -- Get the name of the attached folder 

3 tell application "Finder" 

4 set theName to name of theAttachedFolder 

5 

6 -- Count the new items 

7 set theCount to length of theNewItems 

8 

9 -- Display an alert indicating that the new items were received 
10 activate 

11 display alert "Attention!" message (theCount & " new items were detected in 


folder " & (quoted form of theName) & "." as string) 


-- Loop through the newly detected items 


repeat with anItem in theNewItems 





ry 
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16 -- Process the current item 


17 

18 -- Move the current item to another folder so it's not processed again 
in the future 

19 

20 end repeat 

21 end tell 


22 end adding folder items to 
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Listing 18-4 AppleScript: Example of the removing folder items from event handler 





1 on removing folder items from theAttachedFolder after losing theRemovedItems 
2 -- Get the name of the attached folder 
3 tell application "Finder" 
4 set theName to name of theAttachedFolder 
5 
6 -- Count the removed items 
7 set theCount to length of theRemovedItems 
8 
9 -- Display an alert indicating that items were removed 
10 activate 
11 display alert "Attention!" message (theCount & " items were removed from 
folder " & (quoted form of theName) & "." as string) 
12 
13 -- Loop through the removed items, performing any additional tasks 
14 repeat with anItem in theRemovedItems 
15 
16 -- Process the current item 
17 
18 end repeat 
19 end tell 
20 end removing folder items from 


Attaching a Folder Action Script to a Folder 


A folder action script must be connected to a folder in order to use it. This is done with Folder Actions Setup, 
an app that’s launched from the Finder’s contextual menu. 


To attach a folder action script to a folder 
1. Control-click the folder in Finder. 


2. Choose Folder Actions Setup from the contextual menu. 


The Folder Actions Setup app launches, the folder is automatically added to the Folders with Actions 
list, and you’re prompted to select a script. 


3. Choose a script to connect to the folder and click Attach. 


ee Folder Actions Setup 
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Cancel _ 


i 























4. Make sure the Enable Folder Actions checkbox is selected, as well as the On checkboxes next to the 
folder. 


eee Folder Actions Setup 


Enable Folder Actions 


On Folders with Actions On — Script 
a: add - new item alert.scpt 








| oe Show Folder + | — | | Edit Script 





Once the script and folder are connected, the folder action event handlers in the script should run when the 
corresponding actions occur. 


NOTE 


Folder Actions Setup can also be used to disable or remove folder action scripts and watched folders. 


The Folder Actions Setup app itself resides in /System/Library/CoreServices/. 


Watching Folders Using an Idle Loop and a Stay Open Script App 


Although folder actions provide efficient folder watching capabilities, some scripters prefer to implement 
customized folder watching workflows that provide more control over the folder watching process. This is 
typically done by creating a stay-open script with an idle handler that checks a folder at regular intervals for 
new items to process. Listing 18-5 demonstrates an idle handler-based script that watches an Input folder on 
the Desktop. 


APPLESCRIPT 


Open in Script Editor 


Listing 18-5 AppleScript: Watch a folder for files using an idle loop 





1 on idle 

2 -- Locate the folder to watch 

3 set theFolder to locateAndCreateFolder(path to desktop folder, "Input") 

4 

5 -- Watch the folder 

6 watchFolder(theFolder) 

7 

8 -- Delay 2 minutes before checking the folder again 

9 return 120 

10 end idle 

11 

12 on watchFolder(theFolder) 

13 

14 -- Check for files in the folder 

15 tell application "Finder" 

16 set theFilesToProcess to every file of theFolder 

1? end tell 

18 

19 -- Stop if there are no files to process 

20 if theFilesToProcess = {} then return 

21 

22 -- Locate an output folder 

23 set theOutputFolder to locateAndCreateFolder(path to desktop folder, "Output") 

24 

25 repeat with aFile in theFilesToProcess 

26 

27 -- Process the current file 

28 

29 -- Move the current file to the output folder so it doesn't get processed 
again 

30 tell application "Finder" 

31 move aFile to theOutputFolder 

32 end tell 

33 

34 end repeat 

35 end watchFolder 

36 

37 -- Locate a folder, creating it if it doesn't exist 


38 on locateAndCreateFolder(theParentFolder, theFolderName) 

39 tell application "Finder" 

40 if ((folder theFolderName of theParentFolder) exists) = false then make new 
folder at theParentFolder with properties {name: theFolderName} 

41 return (folder theFolderName of theParentFolder) as alias 

42 end tell 

43 end locateAndCreateFolder 


Folder Watching Best Practices 


Regardless of what method you use for folder watching, follow these best practices to produce an efficient and 
reliable workflow: 


¢ Wait for items to finish writing to disk before processing them. 


+ Move processed items to an output folder so the same items aren’t detected and processed a second 
time. 


* Handle errors gracefully, such as by moving problematic items to an error folder so other processing can 
proceed. 


* Bring dialogs and alerts to the front so they’re visible and can be addressed. 
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Manipulating Text 


Manipulating text is one of the most common tasks performed in scripts. AppleScript and JavaScript both 
possess some basic text manipulation functions and properties that allow you to concatenate text, get the 
length of a string, and more. Overall, JavaScript has a much wider-range of built-in language-level text 
manipulation functions. Custom scripting is usually required to manipulate text with AppleScript. 


NOTE 


For general information about working with text in AppleScript, see the text class reference documentation in 
AppleScript Language Guide. 


In JavaScript, the St ring object provides a range of text processing functions. Information about this object 
can be found here. JavaScript also provides a RegExp constructor, which can be used for pattern matching. 
Information about this constructor can be found here. 


Changing the Case of Text 


The handlers in Listing 19-1 and Listing 19-2 convert text to uppercase or lowercase. To use these handlers, 
provide some source text and a case to apply—upper or lower. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-1 AppleScript: Handler that converts text to uppercase or lowercase 


on changeCaseOfText(theText, theCaseToSwitchTo) 
if theCaseToSwitchTo contains "lower" then 
set theComparisonCharacters to "ABCDEFGHIIKLMNOPQRSTUVWXYZ" 
set theSourceCharacters to "“abcdefghijklmnopqrstuvwxyz" 
else if theCaseToSwitchTo contains "upper" then 


set theComparisonCharacters to "abcdefghijklmnopqrstuvwxyz" 


else 


return theText 


end if 


set theAlteredText to "" 


1 
2 
3 
4 
5 
6 
? set theSourceCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
8 
9 
) 
1 
2 repeat with aCharacter in theText 

3 


set theOffset to offset of aCharacter in theComparisonCharacters 
14 if theOffset is not @ then 
15 set theAlteredText to (theAlteredText & character theOffset of 


theSourceCharacters) as string 





16 else 

17 set theAlteredText to (theAlteredText & aCharacter) as string 
18 end if 

19 end repeat 

20 return theAlteredText 


21 end changeCaseOfText 
JAVASCRIPT 


Open in Script Editor 


Listing 19-2 JavaScript: Function that converts text to uppercase or lowercase 


1 function changeCaseOfText(text, caseToSwitchTo) { 
2 var alteredText = text 

3 if (caseToSwitchTo === "lower") { 

4 alteredText = alteredText.toLowerCase() 

5 } 

6 else if (caseToSwitchTo === "upper") { 


i alteredText = alteredText.toUpperCase() 


8 t 
9 return alteredText 
10 + 


Listing 19-3 and Listing 19-4 show how to call the handlers in Listing 19-1 and Listing 19-2 to convert text to 
uppercase. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-3 AppleScript: Calling a handler to convert text to uppercase 


1 changeCaseOfText ("scripting is awesome!", "“upper") 


2 --> Result: "SCRIPTING IS AWESOME!" 


JAVASCRIPT 
Open in Script Editor 
Listing 19-4 JavaScript: Calling a function to convert text to uppercase 


d changeCaseOfText ("scripting is awesome!", "upper") 


2 // Result: "SCRIPTING IS AWESOME!" 


Listing 19-5 and Listing 19-6 show how to call the handlers in Listing 19-1 and Listing 19-2 to convert text to 
lowercase. 


APPLESCRIPT 

Open in Script Editor 

Listing 19-5 AppleScript: Calling a handler to convert text to lowercase 

1 changeCaseOfText ("DOING REPETITIVE WORK IS BORING", "lower") 
2 --> Result: "doing repetitive work is boring" 

JAVASCRIPT 

Open in Script Editor 

Listing 19-6 JavaScript: Calling a function to convert text to lowercase 


1 changeCaseOfText ("DOING REPETITIVE WORK IS BORING", "lower") 


2 // Result: "doing repetitive work is boring" 


NOTE 


When you use AppleScriptObjC or JavaScriptObjC, you can use methods of the NSSt ring class to change 
the case of text. Listing 19-7 and Listing 19-8 demonstrate how to do this. 


APPLESCRIPT 
Open in Script Editor 


Listing 19-7 AppleScriptObjC: Handler for changing text to uppercase or lowercase 


use framework "Foundation" 


al 

2 

3 on changeCaseOfText(theText, theCase) 

4 -- Create an NSString object from the passed text 
5 


set theText to stringWithString_(theText) of NSString of current 


application 

6 

7 -- Apply the appropriate transformation to the NSString object 

8 if theCase contains "lower" then 

9 set theNewText to lowercaseString() of theText 
10 else if theCase contains "upper" then 
el set theNewText to uppercaseString() of theText 
12 else 
13 set theNewText to capitalizedString() of theText 
14 end if 
15 


16 -- Convert the NSString to an AppleScript string 


17 return (theNewText as string) 
18 end changeCaseOfText 


JAVASCRIPT 


Open in Script Editor 


Listing 19-8 JavaScriptObjC: Function for changing text to uppercase or lowercase 


1 function changeCaseOfText(text, caseToSwitchTo) { 
2 // Convert the passed text to an NSString object 
3 var alteredText = $(text) 
4 
5 // Apply the appropriate transformation to the NSString object 
6 if (caseToSwitchTo === "lower") { 
7 alteredText = alteredText. lowercaseString 
8 a) 
9 else if (caseToSwitchTo === "upper") { 
10 alteredText = alteredText.uppercaseString 
11 } 
12 
13 // Convert the NSString to an AppleScript string 
14 return alteredText.js 
15 } 


Finding and Replacing Text in a String 


The handler in Listing 19-9 can be used to find and replace text in a string. To use it, provide some source 
text, a string to find, and a replacement string. This handler replaces any found instances of the specified 
search string. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-9 AppleScript: Handler that finds and replaces text in a string 


1 on findAndReplaceInText(theText, theSearchString, theReplacementString) 
2 set AppleScript's text item delimiters to theSearchString 

3 set theTextItems to every text item of theText 

4 set AppleScript's text item delimiters to theReplacementString 

5 set theText to theTextItems as string 

6 set AppleScript's text item delimiters to "" 
7 return theText 

8 end findAndReplaceInText 


Listing 19-10 shows how to call the handler in Listing 19-9. 
APPLESCRIPT 

Open in Script Editor 

Listing 19-10 AppleScript: Calling a handler to find and replace text in a string 


1 set theText to "On Tuesday, I told you to have the report ready by next Tuesday." 
2 set theText to findAndReplaceInText(theText, "Tuesday", "Friday") 
3 --> Result: "On Friday, I told you to have the report ready by next Friday." 


In JavaScript, the String object’s replace() method is used to find and replace text in a string, as shown in 
Listing 19-11. Unlike the previous AppleScript example, this function replaces only the first occurrence of the 
found text. 


JAVASCRIPT 
Open in Script Editor 
Listing 19-11 JavaScript: Finding and replacing the first occurrence of text in a string 


1 var text = "On Tuesday, I told you to have the report ready by next Tuesday." 


2 text = text. replace("Tuesday", "Friday") 
3 // Result: "On Friday, I told you to have the report ready by next Tuesday." 


The replace() method can be combined with a regular expression to replace every occurrence of the found 
text, as shown in Listing 19-12. 


JAVASCRIPT 
Open in Script Editor 


Listing 19-12 JavaScript: Finding and replacing every occurrence of text in a string 


1 var text = "On Tuesday, I told you to have the report ready by next Tuesday. 
2 text = text. replace(/Tuesday/g, "Friday") 
3 // Result: "On Friday, I told you to have the report ready by next Friday." 


NOTE 


When you use AppleScriptObjC or JavaScriptObjC, you can use methods of the NSString class to perform a 
find and replace in text. The handlers in Listing 19-13 and Listing 19-14 demonstrate how to do this. 


APPLESCRIPT 
Open in Script Editor 


Listing 19-13 AppleScriptObjC: Handler that finds and replaces every occurrence of text in a string 


use framework "Foundation" 


-- Create an NSString object from the passed AppleScript string 


al 

2: 

z] on findAndReplaceInText(theText, theSearchString, theReplacementString) 
4 

5 set theText to stringWithString_(theText) of NSString of current 


application 

6 -- Call an NSString replacement method on the newly created NSString 
object 

zs set theText to 


stringByReplacingOccurrencesOfString_withString_(theSearchString, 
theReplacementString) of theText 
-- Convert from an NSString to an AppleScript string 
return (theText as string) 
10 end findAndReplaceInText 


JAVASCRIPT 


Open in Script Editor 


Listing 19-14 JavaScriptObjC: Function that finds and replaces every occurrence of text in a string 


1 function findAndReplaceInText(text, searchString, replacementString) { 

2 // Create an NSString object from the passed string 

3 var alteredText = $(text) 

4 // Call an NSString replacement method on the newly created NSString 


object 

5 alteredText = 
alteredText.stringByReplacingOccurrencesOfStringWithString(searchString, 
replacementString) 

6 // Convert from an NSString to a JavaScript string 


return alteredText.js 


Getting the Characters of a String 

Listing 19-15 and Listing 19-16 show how to get a list of characters in a string. 
APPLESCRIPT 

Open in Script Editor 

Listing 19-15 AppleScript: Get the characters of a string 


it set theText to "The quick brown fox jumps over a lazy dog." 


2 characters of theText 


3 --> Result: {70 "he Nel", " me "q', UT hae "ae ee ae " ms Hpi Se Hon, "yy : 
Tr 
ae "a", " Le a "a", mage yn " oar oa a non, Ng", ey 

JAVASCRIPT 

Open in Script Editor 

Listing 19-16 JavaScript: Get the characters of a string 

1 var text = "The quick brown fox jumps over a lazy dog." 

2 text.split("") 

3 // Result: ("i i ota "e", " mS ng” "uy no, ih cage mKIS, u Her "pb", ny HOM 'w", 
Hy np gn yg ge gn cn npn gn no gn yn nan en 
me ma", " ms a "ary yr Ae wy " “ "a", nom, ng" Cr | 


Getting the Length of String 


Listing 19-17 and Listing 19-18 show how to get the length of—the number of characters in—a string. 


APPLESCRIPT 

Open in Script Editor 

Listing 19-17 AppleScript: Get the length of a string 

1 set theText to "The quick brown fox jumps over a lazy dog." 
2 length of theText 

3 --> Result: 42 

JAVASCRIPT 

Open in Script Editor 

Listing 19-18 JavaScript: Get the length of a string 


1 var text = "The quick brown fox jumps over a lazy dog." 


2 text. length 
3 // Result: 42 


Getting the Paragraphs of a String 

Listing 19-19 and Listing 19-20 show how to get a list of paragraphs in a string. 
APPLESCRIPT 

Open in Script Editor 

Listing 19-19 AppleScript: Get the characters of a string 


set theText to "* Sal 
* Ben 

* Chris 

* David" 


paragraphs of theText 


ou fF WN PR 


--> Result: {"*x Sal", "*x Ben", "* Chris", "* David"} 


JAVASCRIPT 
Open in Script Editor 
Listing 19-20 JavaScript: Get the characters of a string 


i var text = ~* Sal 
2 * Ben 

3 * Chris 
4 


* David* 


6 text.split("\n") 


7 // Result: ["*x Sal", "x Ben", "* Chris", "* David"] 


Getting the Position of Text in a String 


To determine the position of text within a string in AppleScript, request its of fset, as shown in Listing 19-21. 
This provides the character number where the first instance of the text begins. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-21 AppleScript: Get the position of text in a string 


i set theText to "The quick brown fox jumps over a lazy dog." 
2 offset of "quick" in theText 
2 --> Result: 5 


NOTE 


In AppleScript, character positions start at 1; the first character in a string has an offset of 1. If the string 
doesn’t include the text provided, then an offset of 0 is returned. 


To determine the position of text within a string in JavaScript, call the index0f() method of the text object, as 
shown in Listing 19-22. 


JAVASCRIPT 
Open in Script Editor 
Listing 19-22 JavaScript: Get the position of text in a string 


i var text = "The quick brown fox jumps over a lazy dog." 
2 text. index0f ("quick") 
3 // Result: 4 


NOTE 


In JavaScript, character positions start at 0; the first character in a string has an index of @. If the string 
doesn’t include the text provided, then an offset of —1 is returned. 


Splitting Text 

The handler in Listing 19-23 splits text into a list, based on a specific delimiter. 
APPLESCRIPT 

Open in Script Editor 

Listing 19-23 AppleScript: Handler that splits text 


on splitText(theText, theDelimiter) 
set AppleScript's text item delimiters to theDelimiter 


set theTextItems to every text item of theText 


a 
2 
3 
4 set AppleScript's text item delimiters to 
5 return theTextItems 

6 


end splitText 


Listing 19-24 shows how to call the handler in Listing 19-23. 
APPLESCRIPT 


Open in Script Editor 


Listing 19-24 AppleScript: Calling a handler to split text based on a delimiter 


i set theText to "The quick brown fox jumps over a lazy dog." 


2 splitText(theText, space) 


3 --> Result: {"The", "quick", "brown", "fox", "jumps", "over", "a", "lazy", "dog."} 


In JavaScript, the String object’s split() method is used to split text based on a delimiter, as shown in 
Listing 19-25. 


JAVASCRIPT 
Open in Script Editor 
Listing 19-25 JavaScript: Function that splits text 


1 var text = "The quick brown fox jumps over a lazy dog." 


2 text.split(" ") 


3 // Result: ["The", "quick", "brown", "fox", "jumps", "over", "a", "lazy", "dog."] 


NOTE 


See Converting a List to a String to learn how to merge strings back together. 


Trimming Text 


The handlers in Listing 19-26 and Listing 19-27 trim text from the beginning or end of a string. To use these 
examples, provide some source text, characters to trim, and a trim direction—beginning (trim from the 
beginning), end (trim from the end), or both (trim from both the beginning and end). 


APPLESCRIPT 
Open in Script Editor 


Listing 19-26 AppleScript: Handler that trims text 





1 on trimText(theText, theCharactersToTrim, theTrimDirection) 
2 set theTrimLength to length of theCharactersToTrim 
3 if theTrimDirection is in {"beginning", “both"} then 
4 repeat while theText begins with theCharactersToTrim 
5 try 
6 set theText to characters (theTrimLength + 1) thru -1 of theText as 
string 
7 on error 
8 -- text contains nothing but trim characters 
9 return ™ 
10 end try 
it end repeat 
12 end if 
13 if theTrimDirection is in {"end", "both"} then 
14 repeat while theText ends with theCharactersToTrim 
15 try 
16 set theText to characters 1 thru -(theTrimLength + 1) of theText as 
string 
17 on error 
18 -- text contains nothing but trim characters 
19 return "" 
20 end try 
21 end repeat 
22 end if 
23 return theText 


24 end trimText 


JAVASCRIPT 


Open in Script Editor 
Listing 19-27 JavaScript: Function that trims text 


1 function trimText(text, charsToTrim, direction) { 


2 var result = text 
3 var regexString = charsToTrim. replace(/[\-\ [\]\/\{\F\(\) \VR\FNV2\V. AVWAAS\ | 1/9, 
"\\$8") 5 
4 if (direction === "beginning" || direction === "both") { 
5 var regex = new RegExp(**(?:${regexString})** ) 
6 result = result.replace(regex, "") 
7 } 
8 if (direction === "end" || direction === "both") { 
9 var regex = new RegExp(*(?:${regexString})*$° ) 
10 result = result.replace(regex, "") 
df + 
12 return result 


Listing 19-28 and Listing 19-29 show how to call the handlers in Listing 19-26 and Listing 19-27 to trim text 
from the beginning of a string. 


APPLESCRIPT 
Open in Script Editor 


Listing 19-28 AppleScript: Calling a handler to trim text from the beginning of a string 


1 trimText("----1----", "-", "beginning") 
2 =—> Result: "1=---" 
JAVASCRIPT 


Open in Script Editor 
Listing 19-29 JavaScript: Calling a function to trim text from the beginning of a string 
1 trimText("----1----", "-", "beginning") 


2 // Result: "1----" 


Listing 19-30 and Listing 19-31 show how to call the handlers in Listing 19-26 and Listing 19-27 to trim text 
from the end of a string. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-30 AppleScript: Calling a handler to trim text from the end of a string 


1 trimText("12345.txt", ".txt", "end") 
2 --> Result: "12345" 


JAVASCRIPT 
Open in Script Editor 
Listing 19-31 JavaScript: Calling a function to trim text from the end of a string 


1 trimText("12345.txt", ".txt", "end") 
2 // Result: "12345" 


Listing 19-32 and Listing 19-33 show how to call the handlers in Listing 19-26 and Listing 19-27 to trim text 
from the beginning and end of a string. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-32 AppleScript: Calling a handler to trim text from the beginning and end of a string 


1 trimText ("x-*—-Benx-*-", "*-", "both") 


2 --> Result: "Ben" 


JAVASCRIPT 
Open in Script Editor 
Listing 19-33 JavaScript: Calling a function to trim text from the beginning and end of a string 


1 trimText ("*-*—-Benx-*-", "*-", "both") 


2 // Result: "Ben" 


NOTE 


When you use AppleScriptObjC or JavaScriptObjC, you can use methods of the NSString class to remove 
whitespace around text. The handlers in Listing 19-34 and Listing 19-35 demonstrate how to do this. 


APPLESCRIPT 


Open in Script Editor 


Listing 19-34 AppleScriptObjC: Handler that removes white space around text 


use framework "Foundation" 


1 

2 

3 on trimWhiteSpaceAroundString(theText) 

4 -- Create an NSString object from an AppleScript string 
5 


set theText to stringWithString_(theText) of NSString of current 


application 

6 -- Trim white space around the NSString 

7 set theWhitespaceCharacterSet to whitespaceCharacterSet of NSCharacterSet 
of current application 

8 set theText to stringByTrimmingCharactersInSet_(theWhitespaceCharacterSet) 
of theText 

9 -- return result coerced to an AppleScript string 

10 return (theText as string) 


11 end trimwhiteSpaceAroundString 


JAVASCRIPT 
Open in Script Editor 


Listing 19-35 JavaScriptObjC: Function that removes white space around text 


1 function trimWhiteSpaceAroundString(text) { 

2 // Create an NSString object from the text 

3 var alteredText = $(text) 

4 // Trim white space around the NSString and return the result 

5 var whitespace = $.NSCharacterSet.whitespaceCharacterSet 

6 return alteredText.stringByTrimmingCharactersInSet (whitespace) .js 
a 


Trimming Paragraphs of Text 


The handlers in Listing 19-36 and Listing 19-37 remove unwanted characters from multiple paragraphs. 


NOTE 


This handler calls the trimText() handler. See Listing 19-26. 


APPLESCRIPT 
Open in Script Editor 
Listing 19-36 AppleScript: Handler that trims text on multiple paragraphs 
on trimParagraphsOfText(theText, theCharactersToTrim, theTrimDirection) 


set theParagraphs to every paragraph of theText 


1 

2 

3 repeat with a from 1 to count of paragraphs of theText 

4 set theCurrentParagraph to item a of theParagraphs 

5 set item a of theParagraphs to trimText(theCurrentParagraph, 
theCharactersToTrim, theTrimDirection) 


6 end repeat 


7 set AppleScript's text item delimiters to return 


8 set theText to theParagraphs as string 
9 set AppleScript's text item delimiters to "" 
10 return theText 


11 end trimParagraphsOfText 


JAVASCRIPT 
Open in Script Editor 
Listing 19-37 JavaScript: Function that trims text on multiple paragraphs 


function trimParagraphsOfText(text, charsToTrim, direction) { 
var paragraphs = text.split("\n") 
for (var i = 0; i < paragraphs.length; i++) { 
var currentParagraph = paragraphs [i] 
paragraphs[i] = trimText(currentParagraph, charsToTrim, direction) 
} 


1 
2 
3 
4 
5 
6 
7 return paragraphs. join("\n") 

8 

Listing 19-38 and Listing 19-39 show how to call the handlers in Listing 19-36 and Listing 19-37. 
APPLESCRIPT 

Open in Script Editor 


Listing 19-38 AppleScript: Calling a handler to trim text from multiple paragraphs 


1 set theText to "* Sal 
2 * Ben 

3 * Chris 

4 * David" 

5 trimParagraphsOfText(theText, "* ", "beginning") 
6 =—> Result: 

7 (x 

8 "Sal 

9 Ben 

10 Chris 

11 David" 

12. x) 

JAVASCRIPT 


Open in Script Editor 


Listing 19-39 JavaScript: Calling a function to trim text from multiple paragraphs 


trimParagraphsOfText(text, "* ", "beginning") 


1 var text = “* Sal 
2 * Ben 

3 * Chris 

4 * David 

5 

6 


// Result: "Sal\nBen\nChris\nDavid" 


NOTE 


In JavaScript, \n represents a newline character. 
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Manipulating Numbers 


Working with and manipulating numbers is an important and regular occurrence in scripting. Basic mathematic 
operations—such as addition, subtraction, multiplication, and division—are language-level features, but some 
other commonly performed operations require custom scripting. 


NOTE 


AppleScript’s language-level mathematical operators are listed in Operators Reference in AppleScript 
Language Guide. 


JavaScript’s language-level arithmetic operators can be found here. JavaScript also includes a built-in Math 
object, which provides a variety of properties and methods for performing common mathematical operations. 
Information about this object can be found here. Several of the JavaScript examples in this chapter call the 
Math.abs() method to get the absolute value of a number. AppleScript does not have an equivalent method. 


Converting a Number to a String 


Scripts often need to convert numbers to string format to display information to the user or populate a 
document. In AppleScript, this conversion can be accomplished most of the time simply by using the coercion 
operator as, as shown in Listing 20-1. 


APPLESCRIPT 
Open in Script Editor 

Listing 20-1 AppleScript: Coercing a number to a string 

1 12 as string 

2 =-> Results "12" 

In JavaScript, the same conversion can be accomplished by calling the toString() method, as shown in 
Listing 20-2. 

JAVASCRIPT 

Open in Script Editor 

Listing 20-2 JavaScript: Coercing a number to a string 


1 num = 12 
2 num. toString() 
3 // Result: "12" 


Converting a Long Number to a String 


In AppleScript, long numeric values are displayed in scientific notation. For example, 1234000000 is displayed 
by a script as 1.234E+9. When this value is coerced to a string, it becomes: "1. 234E+9". The handler in Listing 
20-3 converts a number, regardless of length, to a string of numeric characters instead of a numeric string in 
scientific notation. 


APPLESCRIPT 
Open in Script Editor 
Listing 20-3 AppleScript: Handler that converts a number to a string, regardless of length 


on convertNumberToString(theNumber) 
set theNumberString to theNumber as string 


set theOffset to offset of "E" in theNumberString 


set thePrefix to text 1 thru (theOffset - 1) of theNumberString 


1 

2 

3 

4 if theOffset = @ then return theNumberString 
5 

6 set theConvertedNumberPrefix to 

7 


if thePrefix begins with "-" then 





8 set theConvertedNumberPrefix to "-" 
9 if thePrefix = "-" then 

10 set thePrefix to "" 

U7. else 

12 set thePrefix to text 2 thru -1 of thePrefix 

13 end if 

14 end if 

15 set theDecimalAdjustment to (text (theOffset + 1) thru -1 of theNumberString) as 
number 

16 set isNegativeDecimalAdjustment to theDecimalAdjustment is less than 0 

17 if isNegativeDecimalAdjustment then 

18 set thePrefix to (reverse of (characters of thePrefix)) as string 

19 set theDecimalAdjustment to -theDecimalAdjustment 

20 end if 

21 set theDecimal0ffset to offset of "." in thePrefix 

22 if theDecimalOffset = @ then 

23 set theFirstPart to "" 

24 else 

25 set theFirstPart to text 1 thru (theDecimalOffset - 1) of thePrefix 

26 end if 

27 set theSecondPart to text (theDecimalOffset + 1) thru -1 of thePrefix 

28 set theConvertedNumber to theFirstPart 

29 set theRepeatCount to theDecimalAdjustment 

30 if (length of theSecondPart) is greater than theRepeatCount then set 
theRepeatCount to length of theSecondPart 

31 repeat with a from 1 to theRepeatCount 

32 try 

33 set theConvertedNumber to theConvertedNumber & character a of 
theSecondPart 

34 on error 

35 set theConvertedNumber to theConvertedNumber & "0" 

36 end try 

a7 if a = theDecimalAdjustment and a is not equal to (length of theSecondPart) 
then set theConvertedNumber to theConvertedNumber & "." 

38 end repeat if theConvertedNumber ends with "." then set theConvertedNumber 
to theConvertedNumber & "Q" 

39 if isNegativeDecimalAdjustment then set theConvertedNumber to (reverse of 
(characters of theConvertedNumber)) as string 

40 return theConvertedNumberPrefix & theConvertedNumber 


41 end convertNumberToString 


Listing 20-3 shows how to call the handler in Listing 20-3. 
APPLESCRIPT 

Open in Script Editor 

Listing 20-4 AppleScript: Calling a handler to convert a long number to a string 


1 convertNumberToString(8.72124243234E+11) 
2 --> Result: "872124243234" 


Adding a Descriptive Suffix to a Number 


The handlers Listing 20-5 and Listing 20-6 convert a number to a string and appends a suffix of "st", "nd", 
"rd", or "th", resulting in strings such as "1st", "2nd", "3rd", and "4th". 


APPLESCRIPT 
Open in Script Editor 


Listing 20-5 AppleScript: Handler that adds a descriptive suffix to a number 





1 on addDescriptiveSuf fixToNumber (theNumber) 
2 -- Determine the suffix to add, based on the last two digits 
3 set theLastDigit to theNumber mod 10 
4 set theLastTwoDigits to theNumber mod 100 
5 set theSuffix to "th" 
6 if {1, -1} contains theLastDigit and {11, -11} does not contain theLastTwoDigits 
then 
7 set theSuffix to "st" 
8 else if {2, -2} contains theLastDigit and {12, -12} does not contain 
theLastTwoDigits then 
9 set theSuffix to "nd" 
10 else if {3, -3} contains theLastDigit and {13, -13} does not contain 
theLastTwoDigits then 
11 set theSuffix to "rd" 
IZ end if 
13 
14 -- Return the number and suffix 
15 return (theNumber as string) & theSuffix 
16 end addDescriptiveSuffixToNumber 
JAVASCRIPT 


Open in Script Editor 


Listing 20-6 JavaScript: Function that adds a descriptive suffix to a number 


1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
1 
2 
3 
4 
5 
6 
7 
8 
9 





20 
21 


function addDescriptiveSuffixToNumber(num) { 
// Convert the number to absolute value 


var integer = Math.abs(num) 


// Determine the suffix to add, based on the last two digits 
var suffix = "th" 
var lastDigit = integer % 10 


var lastTwoDigits = integer % 100 


if (lastDigit === 1 && lastTwoDigits !== 11) { 
suffix = "st" 

+ 

else if (lastDigit === 2 && lastTwoDigits !== 12) { 
suffix = "nd" 

+ 

else if (lastDigit === 3 && lastTwoDigits !== 13) { 
suffix = "rd" 

be 


// Return the number and suffix 


return num.toString() + suffix 


Listing 20-7 and Listing 20-8 show how to test the handlers in Listing 20-5 and Listing 20-6 by looping through 
a range of positive and negative numbers. 


APPLESCRIPT 


Open in Script Editor 


Listing 20-7 AppleScript: Testing a handler that adds a descriptive suffix to a number 


aA uu FPF WN BR 


set theTestResults to '"" 
repeat with a from -10 to 10 
set theTestResults to theTestResults & addDescriptiveSuffixToNumber(a) 
if a is less than 10 then set theTestResults to theTestResults &", " 
end repeat 


theTestResults 


7 --> Result: "-10th, -9th, -8th, -7th, -6th, -5th, -4th, -3rd, -2nd, -1st, 0, 1st, 
2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th, 10th" 


JAVASCRIPT 
Open in Script Editor 


Listing 20-8 JavaScript: Testing a function that adds a descriptive suffix to a number 


1 var testResults = "" 

2 for (var i = -10; i <= 10; i++) { 

3 testResults += addDescriptiveSuffixToNumber (i) 

4 if (i < 10) { 

5 testResults +=", " 

6 } 

7 4} 

8 testResults 

9 // Result: "-10th, -9th, -8th, -7th, -6th, -5th, -4th, -3rd, -2nd, -1st, Oth, 1st, 


2nd, 3rd, 4th, 5th, 6th, 7th, 8th, 9th, 10th" 
Listing 20-9 and Listing 20-10 show how to call the handlers in Listing 20-5 and Listing 20-6 to identify 
positions of items in a list. 
APPLESCRIPT 
Open in Script Editor 
Listing 20-9 AppleScript: Example script that calls a handler to identify the descriptive numeric position of items in a list 


set thePersonList to {"Sal", "Ben", "Chris", "David"} 
set theListLength to length of thePersonList 
repeat with a from 1 to theListLength 
set theSuffixedNumber to addDescriptiveSuffixToNumber(a) 


set thePerson to item a of thePersonList 


ao uu BF WN PR 


display dialog "The " & theSuffixedNumber & " person in list is " & thePerson & 


7 end repeat 


JAVASCRIPT 
Open in Script Editor 


Listing 20-10 JavaScript: Example script that calls a function to identify the descriptive numeric position of items in a list 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var personList = ["Sal", "Ben", "Chris", "David"] 

5 var listLength = personList. length 

6 for (var i = 0; i < listLength; i++) { 

7 var suffixedNum = addDescriptiveSuffixToNumber(i + 1) 

8 var person = personList [il] 

9 app.displayDialog(* The ${suffixedNum} person in list is ${person}.*) 
10 + 


Adding Leading Zeros to a Number 


The handlers in Listing 20-11 and Listing 20-12 convert a number to a string and prepends it with leading 
zeros until it reaches a certain length. They accept two parameters—the number to add leading zeros to and 
the maximum number of leading zeros to add. For example, if the maximum number of leading zeros is set to 
2, the results range from 001 to 999. If the maximum number of leading zeros is 3, the results range from 0001 
to 9999, and so on. 


APPLESCRIPT 


Open in Script Editor 


Listing 20-11 AppleScript: Handler that adds leading zeros to a number 





1 on addLeadingZerosToNumber(theNumber, theMaxLeadingZeroCount) 
2 -- Determine if the number is negative 
3 set isNegative to theNumber is less than @ 
4 
5 -- Determine when the maximum number of digits will be reached 
6 set theThreshold to (10 * theMaxLeadingZeroCount) as integer 
7 
8 -- If the number is shorter than the maximum number of digits 
9 if theNumber is less than theThreshold then 
10 -- If the number is negative, convert it to positive 
11 if isNegative = true then set theNumber to -theNumber 
12 
13 -- Add the zeros to the number 
14 set theLeadingZeros to '"" 
15 set theDigitCount to length of ((theNumber div 1) as string) 
16 set theCharacterCount to (theMaxLeadingZeroCount + 1) - theDigitCount 
17 repeat theCharacterCount times 
18 set theLeadingZeros to (theLeadingZeros & "@") as string 
19 end repeat 
20 
21 -- Make the number negative, if it was previously negative 
22 if isNegative = true then set theLeadingZeros to "-" & theLeadingZeros 
23 
24 -- Return the prefixed number 
25 return (theLeadingZeros & (theNumber as text)) as string 
26 
27 -- If the number is greater than or equal to the maximum number of digits 
28 else 
29 -- Return the original number 
30 return theNumber as text 
31 end if 
32 end addLeadingZerosToNumber 
JAVASCRIPT 


Open in Script Editor 


Listing 20-12 JavaScript: Function that adds leading zeros to a number 


1 
2 
3 
4 
5 
6 
7 
8 
9 
10 
1 
2 
3 
4 
5 
6 
7 
8 
9 





20 
21 
22 


function addLeadingZerosToNumber(num, maxLeadingZeroCount) { 


var leadingZeros = 


// Convert the number to absolute value 


var absNum = Math.abs (num) 


// Determine when the maximum number of digits will be reached 


var threshold = Math.pow(10, maxLeadingZeroCount) 


// If the number is shorter than the maximum number of digits 
if (absNum < threshold) { 

// Prepare a leading zeros string 

var digitCount = Math.trunc(absNum).toString(). length 

var charCount = maxLeadingZeroCount + 1 - digitCount 

for (var i = 0 ; i < charCount; i++) { 


leadingZeros += "0" 


// Add the zeros to the number 
var result = *${leadingZeros}${absNum}* 


23 // Make the number negative, if it was previously negative 
24 if (num < @) { 


25 result = *-${result}* 

26 } 

27 // Return the prefixed number 
28 return result 

29 } 


Listing 20-13 and Listing 20-14 show how to call the handlers in Listing 20-11 and Listing 20-12. 
APPLESCRIPT 

Open in Script Editor 

Listing 20-13 AppleScript: Calling a handler to add leading zeros to a number 


1 addLeadingZerosToNumber(9, 3) 
2 --> Result: "0009" 


JAVASCRIPT 
Open in Script Editor 
Listing 20-14 JavaScript: Calling a function to add leading zeros to a number 


1 addLeadingZerosToNumber(9, 3) 
2 // Result: "0009" 


Commaz-Delimiting a Number 


The handlers Listing 20-15 and Listing 20-16 comma-delimit a numeric value and converts it to a string. 


NOTE 


These handlers call the convertNumberToString() handler. See Listing 20-3. 


APPLESCRIPT 
Open in Script Editor 
Listing 20-15 AppleScript: Handler that comma-delimits a number 


on convertNumberToCommaDelimitedString(theNumber) 
-- Convert the number to a string 


set theNumber to convertNumberToString(theNumber) 


-- Determine the length of the number 


-- Reverse the number so a comma can be added every 3 digits 


set theNumber to (reverse of every character of theNumber) as string 


1 
2 
3 
4 
5 
6 set theNumberLength to length of theNumber 
7 
8 
9 
i) 
1 


-- Loop through the number's digits, add commas, and put the numbers back in the 
correct order 
2 set theConvertedNumber to "" 
3 repeat with a from 1 to theNumberLength 
14 if a is theNumberLength or (a mod 3) is not @ then 

5 set theConvertedNumber to (character a of theNumber & 
theConvertedNumber) as string 
16 else 
17 set theConvertedNumber to ("," & character a of theNumber & 
theConvertedNumber) as string 


18 end if 





19 end repeat 


21 -- Return the comma delimited number 
22 return theConvertedNumber 

23 end convertNumberToCommaDelimitedString 
JAVASCRIPT 


Open in Script Editor 


Listing 20-16 JavaScript: Function that comma-delimits a number 


1 
2 
3 
4 
5 
6 
7 
8 
9 
1) 
1 
2 
3 
4 
5 


16 
17 
18 
19 
20 
21 
22 
23 
24 
25 
26 





function convertNumberToCommaDelimitedString(num) { 
// Convert the number to a string 
var numString = num.toString() 
if (numString.indexOf("e") !=- 1) { 


numString = convertNumberToString(numString) 


// Reverse the number so a comma can be added every 3 digits 
numString = numString.split("").reverse().join("") 


var numStringWithCommas = "" 


// Determine the length of the number 


var numStringLength = numString. length 


// Loop through the number's digits, add commas, and put the numbers back in the 
correct order 
for (var i = 0; i < numStringLength; i++) { 
var toPrepend = numString[il 
if (i != numStringLength - 1 & ((i +1) % 3) == 0) { 
toPrepend = "," + toPrepend 
} 


numStringWithCommas = toPrepend + numStringWithCommas 


// Return the comma delimited number 


return numStringWithCommas 


Listing 20-17 and Listing 20-18 shows how to call the handlers in Listing 20-15 and Listing 20-16. 


APPLESCRIPT 


Open in Script Editor 


Listing 20-17 AppleScript: Calling a handler to comma-delimit a number 


1 convertNumberToCommaDe LimitedSt ring (872124243234) 
2  -+> Result: "872,124,243,234" 
JAVASCRIPT 


Open in Script Editor 


Listing 20-18 JavaScript: Calling a function to comma-delimit a number 


1 


convertNumberToCommaDe LimitedSt ring (872124243234) 
// Result: "872,124,243,234" 


NOTE 


When you use AppleScriptObjC or JavaScriptObjC, you can use methods of the NSNumberFormatter to 
format numbers in different ways. 


The handlers in Listing 20-19 and Listing 20-20 convert a number to a string by returning a comma-delimited, 
rounded, localized decimal value. For example: (3.64525432506E+5 at 0 places converts to "364525", 
3.64525432506E+5 at 3 places converts to "364525.433", and @.2375 at 2 places converts "0.24". 


APPLESCRIPT 


Open in Script Editor 


Listing 20-19 AppleScriptObjC: Handler that converts a number to a comma-delimited, rounded, 
localized decimal value 


1 use framework "Foundation" 





i} on convertNumberToDecimalString(theNumber, theNumberOfDecimalPlaces) 

4 if theNumberOfDecimalPlaces is greater than @ then 

5) set theDecimalIndicators to "." 

6 repeat theNumberOfDecimalPlaces times 

7 set theDecimalIndicators to theDecimalIndicators & "#" 

8 end repeat 

9 else 

(1) set theDecimalIndicators to "" 

1 end if 

2 set theFormatter to init() of alloc() of NSNumberFormatter of current 
application 

3 setFormat_("0" & theDecimalIndicators) of theFormatter 

4 set theFormattedNumber to stringFromNumber_(theNumber) of theFormatter 

5 return (theFormattedNumber as string) 

6 end convertNumberToDecimalString 

JAVASCRIPT 


Open in Script Editor 


Listing 20-20 JavaScriptObjC: Function that converts a number to a comma-delimited, rounded, 
localized decimal value 


1 function convertNumberToDecimalString(number, numberOfDecimalPlaces) { 
2 var decimalIndicators = "" 

5 if (numberO0fDecimalPlaces > 0) { 

4 decimalIndicators = "." 

5 for (var i = 0; i < numberOfDecimalPlaces; i++) { 

6 decimalIndicators += "#" 

7 } 

8 + 

9 var formatter = $.NSNumberFormatter.new 
10 formatter. format = ‘@${decimalIndicators}* 
11 var formattedNumber = formatter.stringFromNumber (number) 
12 return formattedNumber.js 


The handlers in Listing 20-21 and Listing 20-22 convert a number to a string by returning a comma-delimited, 
rounded, localized percentage value. For example: 0.2345 to "23%" or @.2375 to "24%". 


APPLESCRIPT 
Open in Script Editor 


Listing 20-21 AppleScriptObjC: Handler that converts a number to a comma-delimited, rounded, 
localized percentage value 


use framework "Foundation" 


i 

2 

z] on convertNumberToPercentageString(theNumber) 

4 set theStyle to NSNumberFormatterPercentStyle of current application 
5 


set theFormattedNumber to 
localizedStringFromNumber_numberStyle_(theNumber, theStyle) of 
NSNumberFormatter of current application 
return (theFormattedNumber as string) 
end convertNumberToPercentageString 


NI 


JAVASCRIPT 
Open in Script Editor 


Listing 20-22 JavaScriptObjC: Function that converts a number to a comma-delimited, rounded, 
localized percentage value 


1 function convertNumberToPercentageString(number) { 
var style = $.NSNumberFormatterPercentStyle 


N 


] var formattedNumber = 
$.NSNumberFormatter. localizedStringFromNumberNumberStyle(number, style) 


4 return formattedNumber.js 


The handlers in Listing 20-23 and Listing 20-24 convert a number to a string by returning a comma-delimited, 
rounded, localized currency value. For example: 9128 to "$9,128.00" or 9978.2485 to "$9,978.25". 


APPLESCRIPT 
Open in Script Editor 


Listing 20-23 AppleScriptObjC: Handler that converts a number to a comma-delimited, rounded, 
localized currency value 


use framework "Foundation" 


al 

2 

3 on convertNumberToCurrencyString(theNumber) 

4 set theStyle to NSNumberFormatterCurrencyStyle of current application 

5 set theFormattedNumber to 
localizedStringFromNumber_numberStyle_(theNumber, theStyle) of 
NSNumberFormatter of current application 


6 return (theFormattedNumber as string) 


~I 


end convertNumberToCurrencyString 


JAVASCRIPT 


Open in Script Editor 


Listing 20-24 JavaScriptObjC: Function that converts a number to a comma-delimited, rounded, 
localized currency value 


fi function convertNumberToCurrencyString(number) { 
var style = $.NSNumberFormatterCurrencyStyle 
var formattedNumber = 


$.NSNumberFormatter. localizedStringFromNumberNumberStyle(number, style) 
4 return formattedNumber.js 


The handlers in Listing 20-25 and Listing 20-26 convert a number to a string by returning a string of a 
numeric value in words. For example: 23 to “twenty-three", 23.75 to "twenty-three point seven five". 


APPLESCRIPT 
Open in Script Editor 


Listing 20-25 AppleScriptObjC: Handler that converts a number to a string of numeric values in 
words 


1 use framework "Foundation" 

2 

3 on convertNumberToWords (theNumber) 

4 set theStyle to NSNumberFormatterSpellOutStyle of current application 
5 set theFormattedNumber to 


localizedStringFromNumber_numberStyle_(theNumber, theStyle) of 
NSNumberFormatter of current application 
6 return (theFormattedNumber as string) 


~I 


end convertNumberToWords 


JAVASCRIPT 


Open in Script Editor 


Listing 20-26 JavaScriptObjC: Function that converts a number to a string of numeric values in 
words 


a function convertNumberToWords(number) { 
a var style = $.NSNumberFormatterSpellOutStyle 
3 var formattedNumber = 
$.NSNumberFormatter. localizedStringFromNumberNumberStyle(number, style) 
4 return formattedNumber.js 
5 + 


In JavaScript, regular expressions can also be used to convert a number to a comma-delimited string even 
more efficiently, as shown in Listing 20-27. 


JAVASCRIPT 


Open in Script Editor 


Listing 20-27 JavaScript: Method that uses regular expressions to comma-delimit a number 


function convertNumberToCommaDelimitedString(num) { 
var numPieces = num.toString().split(".") 
numPieces[0] = numPieces[Q].replace(/\B(?=(\d{3})+(?!\d))/g, ",")3 
return numPieces.join(".") 
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Determining if a Number is an Odd Number 


The handlers in Listing 20-28 and Listing 20-29 determine whether a whole number is even or odd. A returned 
value of false indicates the passed number is even; a returned value of true indicates the passed number is 


odd. 

APPLESCRIPT 

Open in Script Editor 

Listing 20-28 AppleScript: Handler that determines whether a number is odd 


on isNumber0Odd(theNumber) 
if theNumber mod 2 is not @ then 


return true 


return false 


1 

2 

3 

4 else 
5 

6 end if 
7 


end isNumberOdd 


JAVASCRIPT 
Open in Script Editor 
Listing 20-29 JavaScript: Method that determines whether a number is odd 


i function isNumberOdd(num) { 
2 return num % 2 !== 


3 } 


Listing 20-30 and Listing 20-31 show how to call the handlers in Listing 20-28 and Listing 20-29. 
APPLESCRIPT 

Open in Script Editor 

Listing 20-30 AppleScript: Calling a handler to determine whether a number is odd 


HE isNumber0Odd (3) 


2 --> Result: true 


JAVASCRIPT 
Open in Script Editor 
Listing 20-31 JavaScript: Calling a method to determine whether a number is odd 


1 isNumber0Odd (3) 
2 // Result: true 


Listing 20-32 and Listing 20-33 show how to call the handlers in Listing 20-28 and Listing 20-29 by prompting 
the user to enter an even number. 


APPLESCRIPT 
Open in Script Editor 


Listing 20-32 AppleScript: Example script that calls a handler to determine whether a user-entered number is odd 


1 repeat 

2 display dialog "Enter an even integer:" default answer "" 

3 try 

4 if text returned of result is not "" then set theNumberProvided to text 
returned of result as integer 

5 if isNumberOdd(theNumberProvided) is false then exit repeat 

6 end try 


7 end repeat 


JAVASCRIPT 
Open in Script Editor 


Listing 20-33 JavaScript: Example script that calls a method to determine whether a user-entered number is odd 


1 var app = Application. currentApplication() 
2 app.includeStandardAdditions = true 

3 

4 while (true) { 

5 var result = app.displayDialog("Enter an even integer:", {defaultAnswer: ""}) 
6 var text = result.textReturned 

7 if (text !== '"") { 

8 var num = Number(text) 

9 if (!isNumberOdd(num)) { 

10 break 

11 } 

12 + 

13 + 


Rounding and Truncating a Number 


The handlers in Listing 20-34 and Listing 20-35 round and truncate a numeric value, and convert it to a string. 
Provide a numeric value and indicate a number of decimal places. 


NOTE 


These handlers call the convertNumberToString() handler. See Listing 20-3. 


APPLESCRIPT 
Open in Script Editor 


Listing 20-34 AppleScript: Handler for rounding and truncating a number 





1 on roundAndTruncateNumber(theNumber, numberOfDecimalPlaces) 

2 if numberOfDecimalPlaces is @ then 

a set theNumber to theNumber + 0.5 

4 return convertNumberToString(theNumber div 1) 

5 end if 

6 

7 set theRoundingValue to "5" 

8 repeat numberOfDecimalPlaces times 

9 set theRoundingValue to "0" & theRoundingValue 
10 end repeat 

11 set theRoundingValue to ("." & theRoundingValue) as number 
12 

13 set theNumber to theNumber + theRoundingValue 

14 
15 set theModValue to "1" 

16 repeat numberOfDecimalPlaces - 1 times 
17 set theModValue to "0" & theModValue 

18 end repeat 
19 set theModValue to ("." & theModValue) as number 

20 

21 set theSecondPart to (theNumber mod 1) div theModValue 

22 if length of (theSecondPart as text) is less than numberOfDecimalPlaces then 
23 repeat numberOfDecimalPlaces - (the length of (theSecondPart as text)) times 
24 set theSecondPart to ("@" & theSecondPart) as string 
25 end repeat 

26 end if 


28 set theFirstPart to theNumber div 1 


29 set theFirstPart to convertNumberToString(theFirstPart) 
30 set theNumber to (theFirstPart & "." & theSecondPart) 
31 

32 return theNumber 


33 end roundAndTruncateNumber 


JAVASCRIPT 
Open in Script Editor 


Listing 20-35 JavaScript: Function for rounding and truncating a number 





1 function roundAndTruncateNumber(num, numDecimalPlaces) { 
2 if (numDecimalPlaces === @) { 
3 num = num + 0.5 
4 return convertNumberToString(num / 1) 
5 iF 
6 
7 var roundingValue = "5" 
8 for (var i = 0; i < numDecimalPlaces; i++) { 
9 roundingValue = "0" + roundingValue 
10 t 
11 
12 roundingValue = Number("@." + roundingValue) 
13 num += roundingValue 
14 
15 var modValue = "1" 
16 
17 for (var i = 0; i < numDecimalPlaces - 1; i++) { 
18 modValue = "0" + modValue 
19 t 
20 
21 modValue = Number("@." + modValue) 
22 
23 var secondPart = Math.floor((num % 1) / modValue) 
24 var secondPartStringLength = secondPart.toString(). length 
25 
26 if (secondPartStringLength < numDecimalPlaces) { 
27 
28 var count = numDecimalPlaces - secondPartStringLength 
29 
30 for (var i = 0; i < count; i++) { 
31 secondPart = "@" + secondPart 
32 } 
33 + 
34 
35 var firstPart = Math. floor(num) 
36 firstPart = convertNumberToString(firstPart) 
37 
38 return ‘${firstPart}.${secondPart}* 
39 + 


Listing 20-36 shows how to call the handler in Listing 20-34. 
APPLESCRIPT 

Open in Script Editor 

Listing 20-36 AppleScript: Calling a handler to round and truncate a number 


1 roundAndTruncateNumber (1.04575, 3) 
2 --> Result: "1.046" 
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Manipulating Lists of Items 


In scripting, a list—typically referred to as an array in JavaScript—is a an ordered collection of values that’s 
stored in a single object. A script can loop through the items of a list in order to process the items individually. 
There are many other tasks scripts commonly performed with lists, such as joining and sorting, which usually 
require custom scripting. 


NOTE 


For general information about working with lists in AppleScript, see the list class reference documentation in 
AppleScript Language Guide. 


In JavaScript, the Array object provides a range of processing functions. Information about this object can be 
found here. 


Looping through a List 


Listing 21-1 and Listing 21-2 show how to incrementally loop through a list. In these examples, a variable—a 
in AppleScript and i in JavaScript—represents an integer value from 1 through the number of items in the list. 
Each loop causes this variable value to increase, and you can use the increment variable to target a specific 
list item. 


APPLESCRIPT 
Open in Script Editor 


Listing 21-1 AppleScript: Incrementally looping through items in a list 


1 set theList to {"Sal", "Ben", "David", "Chris"} 

2 repeat with a from 1 to length of theList 

3 set theCurrentListItem to item a of theList 

4 -- Process the current list item 

5 display dialog theCurrentListItem & " is item" & a & " in the list." 
6 end repeat 

JAVASCRIPT 


Open in Script Editor 
Listing 21-2 JavaScript: Incrementally looping through items in an array 
var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var array = ["Sal", "Ben", "David", "Chris"] 


var arrayLength = array.length 


for (var i = 0; i < arrayLength; i++) { 


var currentArrayItem = array[il] 
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// Process the current array item 


bh 
Ss 


app.displayDialog(*${currentArrayItem} is item ${i + 1} in the array.) 
11 + 


A script can also loop through a list of items more directly by dynamically assigning a list item to a variable. In 
Listing 21-3 and Listing 21-4, a variable—theCurrentListItem in AppleScript and currentArraylItem in 
JavaScript—represents the item matching the current loop. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-3 AppleScript: Directly looping through items in a list 


1 set theList to {"Sal", "Ben", "David", "Chris"} 


2 repeat with theCurrentListItem in theList 

3 -- Process the current list item 

4 display dialog theCurrentListItem & " is an item in the list." 
5 


end repeat 


JAVASCRIPT 
Open in Script Editor 
Listing 21-4 JavaScript: Directly looping through items in an array 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var array = ["Sal", "Ben", "David", "Chris"] 
var arrayLength = array.length 
for (var currentArrayItem of array) { 

// Process the current array item 


app.displayDialog(*${currentArrayItem} is an item in the array.) 
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NOTE 


For more information about looping through list items in AppleScript, see Control Statements Reference in 
AppleScript Language Guide. 


Converting a List to a String 


The handler in Listing 21-5 joins a list of strings together in AppleScript, separating them by a specific 
delimiter. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-5 AppleScript: Handler that converts a list of strings into a single string 


on convertListToString(theList, theDelimiter) 
set AppleScript's text item delimiters to theDelimiter 


set theString to theList as string 


cl 
2 
3 
4 set AppleScript's text item delimiters to 
5 return theString 

6 


end convertListToString 


Listing 21-6 shows how to call the handler in Listing 21-5. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-6 AppleScript: Calling a handler to convert a list of strings into a single string 


1 set theList to {"The", "quick", "brown", "fox", "jumps", "over", "a", "lazy", 
"dog."} 
2 convertListToString(theList, space) 


3 --> Result: "The quick brown fox jumps over a lazy dog." 


In JavaScript, custom scripting isn’t required to perform this operation. The Array object has a join() method, 
which can be called to merge a list of items together, as shown in Listing 21-7. 


JAVASCRIPT 
Open in Script Editor 
Listing 21-7 JavaScript: Calling a function to convert an array of strings into a single string 


1 var array = ["The", "quick", "brown", "fox", "jumps", "over", "a", "lazy", "dog."] 


2 var array.join(" ") 


3 // Result: "The quick brown fox jumps over a lazy dog." 


NOTE 


See Splitting Text to learn how to break text apart, based on a specific delimiter. 


When you use AppleScriptObjC or JavaScriptObjC, you can use methods of the NSArray class to convert a 
list of strings into a single string. The handlers in Listing 21-8 and Listing 21-9 demonstrate how to do this. 


APPLESCRIPT 


Open in Script Editor 


Listing 21-8 AppleScriptObjC: Handler that converts a list of strings into a single string 


on convertListToString(theList, theDelimiter) 
set theArray to arrayWithArray_(theList) of NSArray of current application 


al 
2: 
3 set theString to componentsJoinedByString_(theDelimiter) of theArray 
4 return (theString as string) 

5 


end convertListToString 


JAVASCRIPT 
Open in Script Editor 


Listing 21-9 JavaScriptObjC: Function that converts an array of strings into a single string 


a function convertArrayToString(array, delimiter) { 

7 array = $(array) 

3 array = array.componentsJoinedByString(delimiter) 
4 return array.js 

5 t 


Counting the Items in a List 

Listing 21-10 and Listing 21-11 show how to get the number of items in a list. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-10 AppleScript: Get the count of the items in a list 


Z set theList to {"Apple Watch", "iMac", "iPhone", "MacBook Pro"} 
2 length of theList 
3 --> Result: 4 


JAVASCRIPT 
Open in Script Editor 
Listing 21-11 JavaScript: Get the count of the items in an array 


1 var array = ["Apple Watch", "iMac", "iPhone", "MacBook Pro"] 
2 array. Length 
3 // Result: 4 


Counting the Occurrences of an Item in a List 

The handlers in Listing 21-12 and Listing 21-13 count how many times an item appears in a list. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-12 AppleScript: Handler that counts the number of times an item appears in a list 


1 on countInstancesOfItemInList(theList, theItem) 
2 set theCount to @ 


3 repeat with a from 1 to count of theList 
4 if item a of theList is theItem then 
5 set theCount to theCount + 1 

6 end if 

7 end repeat 

8 return theCount 

9 end countInstancesOfItemInList 


JAVASCRIPT 
Open in Script Editor 


Listing 21-13 JavaScript: Function that counts the number of times an item appears in an array 


1 function countInstancesOfItemInArray(array, item) { 
2 var count = @ 

3 for (var element of array) { 

4 if (element === item) { 

5 count++ 

6 } 

7 t 

8 return count 

9 + 


Listing 21-14 and Listing 21-15 show how to call the handlers in Listing 21-12 and Listing 21-13. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-14 AppleScript: Calling a handler to count the number of times an item appears in a list 


1 set theList to {"Sal", "Jen", "Ben", "David", "Chris", "Jen"} 
2 countInstancesOfItemInList(theList, "Jen") 


3 --> Result: 2 


JAVASCRIPT 
Open in Script Editor 
Listing 21-15 JavaScript: Calling a function to count the number of times an item appears in an array 


1 var array = ["Sal", "Jen", "Ben", "David", "Chris", "Jen"] 
2 countInstancesOfItemInArray(array, "Jen") 


3 // Result: 2 


Determining if a List Contains a Specific Item 

Listing 21-16 and Listing 21-17 return a true or false value, indicating the presence of an item in a list. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-16 AppleScript: Check for the existence of an item in a list 


x set theList to {"Sal", "Ben", "David", "Chris"} 
2 theList contains "Lizzie" 


3 --> false 


JAVASCRIPT 
Open in Script Editor 
Listing 21-17 JavaScript: Check for the existence of an item in an array 


1 var array = ["Sal", "Ben", "David", "Chris"] 


2 array.includes("Lizzie") 


3 // Result: false 


Listing 21-18 and Listing 21-19 demonstrate how to add an item to a list only if the list doesn’t already contain 
the item. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-18 AppleScript: Add an item to a list only if the list doesn’t contain the item 


1 set theList to {"Sal", "Ben", "David", "Chris"} 
2 if theList does not contain "Jen" then 

3 set end of theList to "Jen" 

4 end if 

5 return theList 

6 


--> Result: {"Sal", "Ben", "David", "Chris", "Jen"} 


JAVASCRIPT 
Open in Script Editor 


Listing 21-19 JavaScript: Add an item to an array only if the array doesn’t contain the item 


1 var array = ["Sal", "Ben", "David", "Chris"] 
2 if (!array.includes("Jen")) { 

3 array.push("Jen") 

4 + 

5 array 

6 


// Result: ["Sal", "Ben", "David", "Chris", "Jen"] 


Determining the Position of an Item in a List 

The handler in Listing 21-20 determines the position of an item the first time it appears in a list. 
APPLESCRIPT 

Open in Script Editor 


Listing 21-20 AppleScript: Handler that determines the position of an item in a list 


1 on getPositionOfItemInList(theItem, theList) 

2 repeat with a from 1 to count of theList 

3 if item a of theList is theItem then return a 
4 end repeat 

5 return 0 

6 end getPositionOfItemInList 


Listing 21-21 shows how to call the handler in Listing 21-20. In AppleScript, list item positions start at 1—the 
first item in a list has a position of 1. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-21 AppleScript: Calling a handler to determine the position of an item in a list 


1 set theList to {"Sal", "Ben", "David", "Chris", "Jen", "Lizzie", "Maddie", "Lillie"} 
2 getPositionOfItemInList("Maddie", theList) 
3 --> Result: 7 


In JavaScript, the indexO0f() method of the Array object can be called to determine the position of an item in 
an array, as shown in Listing 21-22. In JavaScript, array item positions start at 0—the first item in an array has 
an index of 0. 


JAVASCRIPT 


Open in Script Editor 


Listing 21-22 JavaScript: Determine the position of an item in an array 


1 var array = ["Sal", "Ben", "David", "Chris", "Jen", "Lizzie", "Maddie", "Lillie] 
2 array. indexOf ("Maddie") 
3 // Result: 6 


The getPosition0fItemInList() AppleScript handler and indexOf() JavaScript method can be used to 
cross-reference data between corresponding lists. In Listing 21-23 and Listing 21-24, a person is located ina 
list by name. Next, the person’s phone extension is located in a corresponding list. 


APPLESCRIPT 

Open in Script Editor 

Listing 21-23 AppleScript: Using cross-referencing to locate an item in a list based on the position of an item in another list 

1 set theNames to {"Sal", "Ben", "David", "Chris", "Jen", "Lizzie", "Maddie", 
"Lillie"} 

2 set theExtensions to {"x1111", "x2222", "x3333", "x4444", "x5555", "x6666", "x7777", 
"x8888"}} 

3 set thePerson to choose from list theNames with prompt "Choose a person:" 

4 if thePerson is false then error number -128 

5 set theExtension to item (getPositionOfItemInList((thePerson as string), theNames) ) 


of theExtensions 


6 display dialog "The phone extension for " & thePerson & " is " & theExtension & "." 
JAVASCRIPT 
Open in Script Editor 


Listing 21-24 JavaScript: Using cross-referencing to locate an item in an array based on the position of an item in another array 


1 var app = Application. currentApplication() 

2 app. includeStandardAdditions = true 

3 

4 var names = ["Sal", "Ben", "David", "Chris", "Jen", "Lizzie", "Maddie", "Lillie'] 

5 var extensions = ["x1111", "x2222", "x3333", "x4444", "x5555", "x6666", "x7777", 
"x8888"] 

6 var people = app.chooseFromList(names, {withPrompt: "Choose a person:"}) 

7 if (!people) { 

8 throw new Error(-128) 

9 } 


10 var person = people[0] 

11 var index = names. indexOf (person) 
12 console. log( index) 

13 var extension = extensions [index] 


14 app.displayDialog(*The phone extension for ${person} is ${extension}.°) 


Determining Multiple Positions of an Item in a List 

The handlers in Listing 21-25 and Listing 21-26 determine every position of an item in a list. 
APPLESCRIPT 

Open in Script Editor 


Listing 21-25 AppleScript: Handler that determines every position of an item in a list 


1 on getPositionsOfItemInList(theItem, theList, listFirstPositionOnly) 

2Z set thePositions to {} 

3 repeat with a from 1 to length of theList 

4 if item a of theList is theItem then 

5 if listFirstPositionOnly = true then return a 

6 set end of thePositions to a 

7 end if 

8 end repeat 

9 if listFirstPositionOnly is true and thePositions = {} then return @ 


10 return thePositions 
11 end getPositionsOfItemInList 


JAVASCRIPT 
Open in Script Editor 


Listing 21-26 JavaScript: Function that determines every position of an item in an array 


1 function getPositionsOfItemInArray(item, array, firstPositionOnly) { 
2 if (firstPositionOnly) { 
3 return array. indexOf (item) 
4 } 
5 var indexes = [] 
6 for (var index = 0; index < array.length; index++) { 
7 var element = array[index] 
8 if (element === item) { 
9 indexes. push( index) 
10 } 
11 + 
12 return indexes 
13 + 


Listing 21-27 and Listing 21-28 show how to call the handlers in Listing 21-25 and Listing 21-26. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-27 AppleScript: Calling a handler to determine every position of an item in a list 


1 set theList to {"Sal", "Ben", "Jen", "David", "Chris", "Lizzie", "Maddie", "Jen", 


"Lillie"} 
2 getPositionsOfItemInList("Jen", theList, false) 
3 --> Result: {3, 8} 
JAVASCRIPT 


Open in Script Editor 
Listing 21-28 JavaScript: Calling a function to determine every position of an item in an array 


1 var array = ["Sal", "Ben", "Jen", "David", "Chris", "Lizzie", "Maddie", "Jen", 
"Lillie"] 
2 getPositionsOfItemInArray("Jen", array, false) 


3 // Result: [2, 7] 


Finding the Highest Numeric Value in a List 


The handlers in Listing 21-29 and Listing 21-30 determine the highest numeric value in a list of items. The 
passed list can contain non-numeric data as well as lists within lists. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-29 AppleScript: Handler that determines the highest numeric value in a list of items 


on getHighestNumberInList(theList) 
set theHighestNumber to false 
repeat with a from 1 to count of theList 


set theCurrentItem to item a of theList 


1 

2 

3 

4 

5 set theClass to class of theCurrentItem 

6 if theClass is in {integer, real} then 

7 if theHighestNumber is "" then 

8 set theHighestNumber to theCurrentItem 
9 


else if theCurrentItem is greater than theHighestNumber then 





10 set theHighestNumber to item a of theList 

11. end if 

12 else if theClass is list then 

13 set theHighValue to getHighestNumberInList(theCurrentItem) 
14 if theHighValue is greater than theHighestNumber then 
15 set theHighestNumber to theHighValue 

16 end if 

17 end if 

18 end repeat 

19 return theHighestNumber 

20 end getHighestNumberInList 

JAVASCRIPT 


Open in Script Editor 


Listing 21-30 JavaScript: Function that determines the highest numeric value in a list of items 


1 function getHighestNumberInList(list) { 

2 var highestNumber = undefined 

3 for (var item of list) { 

4 var number = undefined 

5 if (item.constructor === Number) { 

6 

7 number = item 

8 } 

9 else if (item.constructor === Array) { 
10 number = getHighestNumberInList (item) 
11 t 
12 if (number != undefined && (highestNumber === undefined || number > 


highestNumber)) { 


highestNumber = number 


return highestNumber 





3 
4 
15 t 
6 
7 
Listing 21-31 and Listing 21-32 show how to call the handlers in Listing 21-29 and Listing 21-30 for a list 
containing a mixture of numbers and strings. 
APPLESCRIPT 
Open in Script Editor 


Listing 21-31 AppleScript: Calling a handler to determine the highest numeric value in a list of numbers and strings 


1 getHighestNumberInList({-3.25, 23, 2345, "sid", 3, 67}) 
2 --> Result: 2345 


JAVASCRIPT 
Open in Script Editor 
Listing 21-32 JavaScript: Calling a function to determine the highest numeric value in a list of numbers and strings 


1 getHighestNumberInList([-3.25, 23, 2345, "sid", 3, 67]) 
2 // Result: 2345 


Listing 21-33 and Listing 21-34 show how to call the handlers in Listing 21-29 and Listing 21-30 for a list 
containing a mixture of numbers, strings, booleans, and lists. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-33 AppleScript: Calling a handler to determine the highest numeric value in a list of different value types 


1 getHighestNumberInList({-3.25, 23, {23, 78695, "bob"}, 2345, true, "sid", 3, 67}) 


2 --> Result: 78695 


JAVASCRIPT 
Open in Script Editor 
Listing 21-34 JavaScript: Calling a function to determine the highest numeric value in a list of different value types 


1 getHighestNumberInList([-3.25, 23, [23, 78695, "bob"], 2345, true, "sid", 3, 67]) 
2 // Result: 78695 


Listing 21-35 and Listing 21-36 show how to call the handlers in Listing 21-29 and Listing 21-30 for a list 
containing only strings. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-35 AppleScript: Calling a handler to determine the highest numeric value in a list of strings 


1 getHighestNumberInList({"this", "list", "contains", "only", "text"}) 


2 --> Result: false 


JAVASCRIPT 
Open in Script Editor 
Listing 21-36 JavaScript: Calling a function to determine the highest numeric value in a list of strings 


1 getHighestNumberInList(["this", "list", "contains", "only", "text"]) 
2 // Result: undefined 


Finding the Lowest Numeric Value in a List 


The handlers in Listing 21-37 and Listing 21-38 determines the lowest numeric value in a list of items. The 
passed list can contain non-numeric data as well as lists within lists. 


APPLESCRIPT 
Open in Script Editor 


Listing 21-37 AppleScript: Handler that determines the lowest numeric value in a list of items 





1 on getLowestNumberInList(theList) 

2 set theLowestNumber to false 

3 repeat with a from 1 to count of theList 

4 set theCurrentItem to item a of theList 

5 set theClass to class of theCurrentItem 

6 if theClass is in {integer, real} then 

7 if theLowestNumber is "" then 

8 set theLowestNumber to theCurrentItem 

9 else if theCurrentItem is less than theLowestNumber then 
10 set theLowestNumber to item a of theList 

11 end if 
12 else if theClass is list then 

13 set theLowValue to getLowestNumberInList(theCurrentItem) 
14 if theLowValue is less than theLowestNumber then 

15 set theLowestNumber to theLowValue 
16 end if 

17 end if 
18 end repeat 
19 return theLowestNumber 


20 end getLowestNumberInList 


JAVASCRIPT 


Open in Script Editor 


Listing 21-38 JavaScript: Function that determines the lowest numeric value in a list of items 


1 function getLowestNumberInList(list) { 
2 var lowestNumber = undefined 
3 for (var item of list) { 
4 var number = undefined 
5 if (item.constructor === Number) { 
6 number = item 
7 } 
8 else if (item.constructor === Array) { 
9 number = getLowestNumberInList (item) 
10 t 
11 if (number != undefined && (lowestNumber === undefined || number < 
lowestNumber)) { 
12 lowestNumber = number 
13 } 
14 + 
15 return lowestNumber 
16 + 





Listing 21-39 and Listing 21-40 show how to call the handlers in Listing 21-37 and Listing 21-38 for a list 
containing a mixture of numbers and strings. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-39 AppleScript: Calling a handler to determine the lowest numeric value in a list of numbers and strings 


1 getLowestNumberInList({-3.25, 23, 2345, "sid", 3, 67}) 
2 --> Result: -3.25 


JAVASCRIPT 
Open in Script Editor 
Listing 21-40 JavaScript: Calling a function to determine the lowest numeric value in a list of strings 


1 getLowestNumberInList([-3.25, 23, 2345, "sid", 3, 67]) 
2 // Result: -3.25 


Listing 21-41 and Listing 21-42 show how to call the handlers in Listing 21-37 and Listing 21-38 for a list 
containing a mixture of numbers, strings, booleans, and lists. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-41 AppleScript: Calling a handler to determine the lowest numeric value in a list of different value types 


1 getLowestNumberInList({-3.25, 23, {-22, 78695, "Sal"}, 2345, true, "sid", 3, 67}) 
2 --> Result: -22 


JAVASCRIPT 
Open in Script Editor 
Listing 21-42 JavaScript: Calling a function to determine the lowest numeric value in a list of different value types 


i getLowestNumberInList([-3.25, 23, [-22, 78695, "bob"], 2345, true, "sid", 3, 67]) 
2 // Result: -22 


Listing 21-43 and Listing 21-44 show how to call the handlers in Listing 21-37 and Listing 21-38 for a list 
containing only strings. 


APPLESCRIPT 
Open in Script Editor 


Listing 21-43 AppleScript: Calling a handler to determine the lowest numeric value in a list of strings 


Zz getLowestNumberInList({"this", "list", "contains", "only", "text"}) 


2 --> Result: false 


JAVASCRIPT 
Open in Script Editor 
Listing 21-44 JavaScript: Calling a function to determine the lowest numeric value in a list of strings 


1 getLowestNumberInList(["this", "list", "contains", "only", "text"]) 


2 // Result: undefined 


Inserting Items into a List 


The handlers in Listing 21-45 and Listing 21-46 insert an item into a list. Provide the item to insert, the list, and 
the position where the item should be inserted. Note that position can be specified in relation to the end of the 
list by using a negative number. 


NOTE 


In JavaScript, the Array class has built-in methods—unshift (inserts at the beginning), splice (inserts at a 
specific position), and push (inserts at the end)—for inserting items into a list, requiring less custom scripting 
than is necessary in AppleScript. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-45 AppleScript: Handler that inserts an item into a list 


on insertItemInList(theItem, theList, thePosition) 
set theListCount to length of theList 
if thePosition is @ then 
return false 
else if thePosition is less than @ then 
if (thePosition * -1) is greater than theListCount + 1 then return false 
else 
if thePosition is greater than theListCount + 1 then return false 


end if 


if (thePosition * -1) is theListCount + 1 then 


set beginning of theList to theItem 


else 


set theList to reverse of theList 


set thePosition to (thePosition x -1) 


if thePosition is 1 then 


set beginning of theList to theItem 


else if thePosition is (theListCount + 1) then 


1 
2 
3 
4 
5 
6 
7 
8 
9 
10 if thePosition is less than @ then 
1 
2 
3 
4 
5 
6 
7 
8 
9 





set end of theList to theItem 

20 else 

21 set theList to (items 1 thru (thePosition - 1) of theList) & theItem 
& (items thePosition thru -1 of theList) 


22 end if 

23 set theList to reverse of theList 

24 end if 

25 else 

26 if thePosition is 1 then 

27 set beginning of theList to theItem 

28 else if thePosition is (theListCount + 1) then 

29 set end of theList to theItem 

30 else 

31 set theList to (items 1 thru (thePosition - 1) of theList) & theItem & 


(items thePosition thru -1 of theList) 


32 end if 
33 end if 
34 return theList 


35 end insertItemInList 


JAVASCRIPT 
Open in Script Editor 
Listing 21-46 JavaScript: Function that inserts an item into an array 


function insertItemInArray(item, array, position) { 
var arrayCount = array. length 

if (Math.abs(position) > arrayCount) { 

return false 


} 
else if (position === @) { 


array.unshift (item) 


else if (position < arrayCount) { 


array.splice(position, ®, item) 


t 


else { 


array.push(item) 


t 


return array 


1 
2 
3 
4 
5 
6 
7 
8 t 
9 
1) 
1 
2 
3 
4 
5 
6 





Listing 21-47 and Listing 21-48 show how to call the handlers in Listing 21-45 and Listing 21-46 to insert a 
single item into a list at a specific position. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-47 AppleScript: Calling a handler to insert a single item at a specific position in a list 


1 set theList to {"Sal", "Ben", "David", "Chris"} 
2 insertItemInList("Jen", theList, 3) 


3 --> Result: {"Sal", "Ben", "Jen", "David", "Chris"} 


JAVASCRIPT 
Open in Script Editor 
Listing 21-48 JavaScript: Calling a function to insert a single item at a specific position in an array 


1 var array = ["Sal", "Ben", "David", "Chris"] 
2 array = insertItemInArray("Jen", array, 2) 


3 // Result = ["Sal", "Ben", "Jen", "David", "Chris"] 


Listing 21-49 and Listing 21-50 show how to call the handlers in Listing 21-45 and Listing 21-46 to insert 
multiple items into a list at a specific position. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-49 AppleScript: Calling a handler to insert multiple items at a specific position in a list 


1 set theList to {"Sal", "Ben", "David", "Chris"} 
2 insertItemInList({"Lizzie", "Maddie", "Lillie"}, theList, 3) 


3 --> Result: {"Sal", "Ben", "Lizzie", "Maddie", "Lillie", "David", "Chris"} 


JAVASCRIPT 
Open in Script Editor 


Listing 21-50 JavaScript: Calling a function to insert multiple items at a specific position in an array 


var array = ["Sal", "Ben", "David", "Chris"] 
var items = ["Lizzie", "Maddie", "Lillie"] 
for (var item of items) { 

array = insertItemInArray(item, array, 2) 
} 


// Result = ["Sal", "Ben", "Lillie", "Maddie", "Lizzie", "David", "Chris"] 
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Listing 21-51 and Listing 21-52 show how to call the handlers in Listing 21-45 and Listing 21-46 to insert a list 
into a list at a specific position. 


APPLESCRIPT 

Open in Script Editor 

Listing 21-51 AppleScript: Calling a handler to insert a list at a specific position in a list 

1 set theList to {"Sal", "Ben", "David", "Chris"} 

2 insertItemInList({{"Lizzie", "Maddie", "Lillie"}}, theList, 3) 

3 --> Result: {"Sal", "Ben", {"Lizzie", "Maddie", "Lillie"}, "David", "Chris"} 
JAVASCRIPT 

Open in Script Editor 

Listing 21-52 JavaScript: Calling a function to insert a list at a specific position in an array 


1 var array = ["Sal", "Ben", "David", "Chris"] 
2 array = insertItemInArray(["Lizzie", "Maddie", "Lillie"], array, 2) 


3. // Result = ["Sal", "Ben", ["Lizzie", "Maddie", "Lillie"], "David", "Chris"] 


Listing 21-53 and Listing 21-54 show how to call the handlers in Listing 21-45 and Listing 21-46 to insert a 
single item at the end of a list. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-53 AppleScript: Calling a handler to insert a single item at the end of a list 


1 set theList to {"Sal", "Ben", "David", "Chris"} 

2 insertItemInList("Jen", theList, -1) 

3 ae {"Sal", "Ben", "David", "Chris", "Jen"} 
JAVASCRIPT 

Open in Script Editor 

Listing 21-54 JavaScript: Calling a function to insert a single item at the end of an array 


‘ var array = ["Sal", "Ben", "David", "Chris"] 
2 array = insertItemInArray("Jen", array, array. length) 


3 // Result = ["Sal", "Ben", "David", "Chris", "Jen"] 


Listing 21-55 and Listing 21-56 show how to call the handlers in Listing 21-45 and Listing 21-46 to insert a 
single item at the second-to-last position in a list. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-55 AppleScript: Calling a handler to insert a single item at the second-to-last position in a list 


1 set theList to {"Sal", "Ben", "David", "Chris"} 
2 insertItemInList("Wanda", theList, -2) 
3 parent {"Sal", "Sue", "Bob", "Wanda", "Carl"} 


JAVASCRIPT 
Open in Script Editor 


Listing 21-56 JavaScript: Calling a function to insert a single item at the second-to-last position of an array 


1 var array = ["Sal", "Ben", "David", "Chris"] 
2 array = insertItemInArray("Jen", array, -1) 


3 // Result = ["Sal", "Ben", "David", "Jen", "Chris"] 


Listing 21-57 and Listing 21-58 show how to call the handlers in Listing 21-45 and Listing 21-46 to insert a 
single item at a nonexistent position in a list. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-57 AppleScript: Calling a handler to insert a single item at a position that doesn’t exist in a list 


if set theList to {"Sal", "Ben", "David", "Chris"} 
2 insertItemInList("Jen", theList, 15) 
3 --> Result: false 


JAVASCRIPT 
Open in Script Editor 
Listing 21-58 JavaScript: Calling a function to insert a single item at a position that doesn’t exist in an array 


1 var array = ["Sal", "Ben", "David", "Chris"] 
2 array = insertItemInArray("Jen", array, 14) 
3 // Result = false 


Replacing Items in a List 


You can replace an item in a list using the syntax shown in Listing 21-59 and Listing 21-60 if you know the 
position of the item you want to replace. 


APPLESCRIPT 
Open in Script Editor 


Listing 21-59 AppleScript: Replacing a specific item in a list based on position 


1 set theList to {"Sal", "Ben", "David", "Chris"} 
2 set item 3 of theList to "Wanda" 

3 return theList 

4 --> Result: {"Sal", "Sue", "Wanda", "Carl"} 
JAVASCRIPT 


Open in Script Editor 
Listing 21-60 JavaScript: Replacing a specific item in an array based on position 


var array = ["Sal", "Ben", "David", "Chris"] 
array[2] = "Wanda" 


array 


PWN PR 


// Result: ["Sal", "Ben", "Wanda", "Chris"] 


The handlers in Listing 21-61 and Listing 21-62 can be used to replace an item in a list when you don’t know 
its position. Provide the item you want to replace, the list, the replacement item, and specify whether to 
replace all instances of the item, or just the first one. 


APPLESCRIPT 
Open in Script Editor 
Listing 21-61 AppleScript: Handler that replaces items in a list 
on replaceItemInList(theItem, theList, theReplacementItem, replaceAll) 


repeat with a from 1 to the count of theList 


1 

2 

3 set theCurrentItem to item a of theList 
4 if theCurrentItem is theItem then 

5 


set item a of theList to theReplacementItem 


6 if replaceAll is false then return theList 
7 end if 

8 end repeat 

9 


return theList 


10 end replaceItemInList 
JAVASCRIPT 


Open in Script Editor 


Listing 21-62 JavaScript: Function that replaces items in an array 


1 function replaceItemInArray(item, array, replacementItem, replaceAll) { 
2 var arrayLength = array. length 

3 for (var i = 0; i < arrayLength; i++) { 

4 var currentArrayItem = array[il] 

5 if (currentArrayItem === item) { 

6 array.splice(i, 1, replacementItem) 
7 if (!replaceAll) { 

8 break 

9 t 

10 } 

11 + 

12 return array 

13 + 


Listing 21-63 and Listing 21-64 show how to call the handlers in Listing 21-61 and Listing 21-62. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-63 AppleScript: Calling a handler to replace items in a list 


1 set theList to {"Sal", "Jen", "Ben", "David", "Chris", "Jen"} 
Z replaceItemInList("Jen", theList, "Lizzie", true) 

3 --> {"Sal", "Lizzie", "Ben", "David", "Chris", "Lizzie"} 
JAVASCRIPT 

Open in Script Editor 


Listing 21-64 JavaScript: Calling a function to replace items in an array 


1 var array = ["Sal", "Jen", "Ben", "David", "Chris", "Jen"] 
2 replaceItemInArray("Jen", array, "Lizzie", true) 


3 // Result: ["Sal", "Lizzie", "Ben", "David", "Chris", "Lizzie"] 


Sorting a List 

The handler in Listing 21-65 sorts a list of strings or numbers in AppleScript. 
APPLESCRIPT 

Open in Script Editor 

Listing 21-65 AppleScript: Handler that sorts a list of strings 


on sortList(theList) 
set theIndexList to {} 
set theSortedList to {} 


repeat (length of theList) times 


1 

2 

3 

4 

5 set theLowItem to "" 
6 repeat with a from 1 to (length of theList) 

7 if a is not in theIndexList then 

8 set theCurrentItem to item a of theList as text 
9 


if theLowItem is '" then 





set theLowItem to theCurrentItem 
set theLowItemIndex to a 
else if theCurrentItem comes before theLowItem then 
set theLowItem to theCurrentItem 
set theLowItemIndex to a 
end if 
end if 
end repeat 
set end of theSortedList to theLowItem 
set end of theIndexList to theLowItemIndex 
end repeat 
return theSortedList 


end sortList 


Listing 21-66 shows how to call the handler in Listing 21-65. 


APPLESCRIPT 


Open in Script Editor 


Listing 21-66 AppleScript: Calling a handler to sort a list of strings 


1 
2 


set theList to {"Sal", "Ben", "David", "Chris"} 
sortList(theList) 


--> Result: {"Ben", "Chris", "David", "Sal"} 


To perform a reverse (descending) sort, use the reverse command, as shown in Listing 21-67. 


APPLESCRIPT 


Open in Script Editor 


Listing 21-67 AppleScript: Calling a handler to sort a list of strings in reverse order 


1 
2 


set theList to {"Sal", "Ben", "David", "Chris"} 
reverse of sortList(theList) 


--> Result: {"Sal", "David", "Chris", "Ben"} 


In JavaScript, the Array object has a sort method, which sorts the array’s items. See Listing 21-68. 


JAVASCRIPT 


Open in Script Editor 


Listing 21-68 JavaScript: Sorting an array of strings 


1 
2 


var array = ["Sal", "Ben", "David", "Chris"] 
array.sort() 


// Result: ["Ben", "Chris", "David", "Sal"] 


As in AppleScript, a sorted JavaScript array can be reversed, as shown in Listing 21-69. 


JAVASCRIPT 


Open in Script Editor 


Listing 21-69 JavaScript: Sorting an array of strings in reverse order 


1 
2 
3 
4 


var array = ["Sal", "Ben", "David", "Chris"] 
array.sort() 
array. reverse() 


// Result: ["Sal", "David", "Chris", "Ben"] 


NOTE 


When you use AppleScriptObjC or JavaScriptObjC, you can use methods of the NSArray class to convert a 
list of strings into a single string. The handlers in Listing 21-70 and Listing 21-71 demonstrate how to do this. 


APPLESCRIPT 
Open in Script Editor 


Listing 21-70 AppleScriptObjC: Handler that sorts a list of strings 


if on sortList(theList) 

set theArray to arrayWithArray_(theList) of NSArray of current application 

3) set theSortedList to 
sortedArrayUsingSelector_("localizedStandardCompare:") of theArray 

4 return (theSortedList as list) 

end sortList 


N 


wu 


JAVASCRIPT 


Open in Script Editor 


Listing 21-71 JavaScriptObjC: Function that sorts an array of strings 


al function sortArray(array) { 


N 


array = $(array) 
3 var sortedArray = 
array.sortedArrayUsingSelector("localizedStandardCompare:") 


return ObjC.deepUnwrap(sortedArray) 
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Displaying Dialogs and Alerts 


Dialogs and alerts are great ways to provide information about a script’s progress, report problems, and allow 
users to make decisions that affect script behavior. 


Displaying a Dialog 


Use the display dialog command, provided by the Standard Additions scripting addition to show a basic 
dialog message to the user, such as the one in Figure 22-1. This dialog was produced by the code in Listing 
22-1 and Listing 22-2. In these examples, a string is passed to the display dialog command as a direct 
parameter. The result of the command is the button the user clicked in the dialog. 


Figure 22-1 A simple dialog 


The curent date and time is Tuesday, October 27, 2015 at 
3:20:21 PM. 


ee 


APPLESCRIPT 
Open in Script Editor 
Listing 22-1 AppleScript: Displaying a simple dialog 


1 set theDialogText to "The curent date and time is " & (current date) & "." 
2 display dialog theDialogText 
3 --> Result: {button returned:"OK"} 


JAVASCRIPT 

Open in Script Editor 

Listing 22-2 JavaScript: Displaying a simple dialog 

var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var dialogText = "The current date and time is " + (app.currentDate()) 
app.displayDialog(dialogText) 
// Result: {"buttonReturned":"0K"} 
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NOTE 


This chapter covers a portion of the display dialog command's capabilities. For example, the display 
dialog command can also be used to collect text entered by the user. This is covered in Prompting for Text. 
For complete information about the display dialog command and its parameters, launch Script Editor, 
open the Standard Additions scripting addition’s dictionary, and navigate to the command’s definition. 


Customizing Dialog Buttons 


By default, a dialog produced by the display dialog command has two buttons—Cancel and OK (the 
default). However, the command also has numerous optional parameters, some of which can be used to 
customize the buttons. 


Use the buttons parameter to provide a list of between one and three buttons. You can optionally use the 
default button parameter to configure one as the default—it’s highlighted and pressing the Return key 


activates it to close the dialog. You can also use the cancel button parameter to configure one as the cancel 
button—pressing Escape or Command-Period (.) activates it to close the dialog and produce a user cancelled 
error. 


The dialog shown in Figure 22-2 has been customized to include Don’t Continue (the cancel button) and 
Continue (the default) buttons. This dialog was produced by the example code in Listing 22-3 and Listing 22-4. 


Figure 22-2 A dialog with custom buttons 


An error has occurred. Would you like to continue? 


Don't Continue 


APPLESCRIPT 
Open in Script Editor 
Listing 22-3 AppleScript: Displaying a dialog with custom buttons 


1 set theDialogText to "An error has occurred. Would you like to continue?" 
2 display dialog theDialogText buttons {"Don't Continue", "Continue"} default button 
"Continue" cancel button "Don't Continue" 


3 --> Result: {{button returned:"Continue"} 


JAVASCRIPT 
Open in Script Editor 
Listing 22-4 JavaScript: Displaying a dialog with custom buttons 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var dialogText = "An error has occurred. Would you like to continue?" 
app.displayDialog(dialogText, { 
buttons: ["Don't Continue", "Continue"], 


defaultButton: "Continue", 
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cancelButton: "Don't Continue" 


PR 
Ss 


) 
// Result: {"buttonReturned":"Continue"} 
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Adding an Icon to a Dialog 


Dialogs can also include an icon, providing users with a visual clue to their importance. You can direct the 
display dialog command to a specific icon by its file path, or resource name or ID if the icon is stored as a 
resource within your script’s bundle. You can also use the standard system icons stop, note, and caution. 
Listing 22-5 and Listing 22-6 display a dialog that includes the system caution icon like the one shown in 
Figure 22-3. 


Figure 22-3 A dialog with an icon 


= The amaunt of available free snace is 


l\a dangerously low. 





APPLESCRIPT 
Open in Script Editor 
Listing 22-5 AppleScript: Displaying a dialog with an icon 


i set theDialogText to "The amount of available free space is dangerously low." 


2 display dialog theDialogText with icon caution 


JAVASCRIPT 
Open in Script Editor 
Listing 22-6 JavaScript: Displaying a dialog with an icon 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var dialogText = "The amount of available free space is dangerously low." 
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app.displayDialog(dialogText, {withIcon: "caution"}) 


Automatically Dismissing a Dialog 


Sometimes, you may want to continue with script execution if a dialog isn’t dismissed by a user within a certain 
timeframe. In this case, you can specify an integer value for the display dialog command’s giving up after 
parameter, causing the dialog to give up and close automatically after a specified period of inactivity. 


Listing 22-7 and Listing 22-8 display a dialog that automatically closes after five seconds of inactivity. 
APPLESCRIPT 

Open in Script Editor 

Listing 22-7 AppleScript: Displaying a dialog that automatically dismisses after a period of inactivity 


1 display dialog "Do, or do not. There is no try." giving up after 5 


2 --> Result: {button returned:"0K", gave up:true} 


JAVASCRIPT 
Open in Script Editor 
Listing 22-8 JavaScript: JavaScript a dialog that automatically dismisses after a period of inactivity 


var app = Application. currentApplication() 
app.includeStandardAdditions = true 


1 

2 

3 

4 var dialogText = "Do, or do not. There is no try." 
5 app.displayDialog(dialogText, {givingUpAfter: 5}) 
6 


// Result: {"buttonReturned":"0K", "gaveUp": true} 


When using the giving up after parameter, the result of the display dialog command includes a gaveUp 
property, a Boolean value indicating whether the dialog was auto-dismissed. This information is useful if you 
want the script to take a different course of action based on whether a dialog is manually or automatically 
dismissed. 


Displaying an Alert 


The display alert command is also provided by the Standard Additions scripting addition. It’s similar to the 
display dialog command, dui with slightly diiferent parameters. One of the display alert commana’s 
optional parameters is message, which lets you provide additional text to display in a separate text field, below 
the bolded alert text. Listing 22-9 and Listing 22-10 show how to display the alert in Figure 22-4, which 


contains bolded alert text, plain message text, and custom buttons. 


Figure 22-4 An alert 


low. Would you like to continue? 


An error has occurred. 
L / The amount of available free space is dangerously 


Don't Continue 





APPLESCRIPT 
Open in Script Editor 
Listing 22-9 AppleScript: Displaying an alert with a message 


i set theAlertText to "An error has occurred." 

2 set theAlertMessage to "The amount of available free space is dangerously low. Would 
you like to continue?" 

3 display alert theAlertText message theAlertMessage as critical buttons {"Don't 
Continue", "Continue"} default button "Continue" cancel button "Don't Continue" 


4 --> Result: {button returned:"Continue"} 


JAVASCRIPT 
Open in Script Editor 


Listing 22-10 JavaScript: Displaying an alert with a message 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var alertText = "An error has occurred." 

5 var alertMessage = "The amount of available free space is dangerously low. Would you 
like to continue?" 

6 app.displayAlert(alertText, { 

7 message: alertMessage, 

8 as: "critical", 

9 buttons: ["Don't Continue", "Continue"], 

10 defaultButton: "Continue", 

11 cancelButton: "Don't Continue" 

12 }) 


13: // Result: {"buttonReturned":"0K"} 


NOTE 


This chapter covers a portion of the display alert command's capabilities. For complete information about 
the display alert command and its parameters, launch Script Editor, open the Standard Additions scripting 
addition’s dictionary, and navigate to the command’s definition. 
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Prompting for Text 


Use the display dialog command’s optional default answer parameter to collect text, such as a username 
or email address, as your script runs. As demonstrated by Figure 23-1, Listing 23-1, and Listing 23-2, the 
inclusion of the default answer parameter automatically adds a text entry field to the resulting dialog. Any 
string you provide for the parameter appears in the text field when the dialog displays. Providing an empty 
string ('"") produces an empty text field. When the dialog dismisses, any text from the field is returned in a 
text returned property of the display dialog command’s result. 


Figure 23-1 A dialog prompting for text input 


\ What's your name? 
\_ Op Jen 


Cancel Continue 


APPLESCRIPT 


Open in Script Editor 


Listing 23-1 AppleScript: Prompting for text input 


1 set theResponse to display dialog "What's your name?" default answer 
note buttons {"Cancel", "Continue"} default button "Continue" 

2 --> {button returned:"Continue", text returned:"Jen"} 

3 display dialog "Hello, " & (text returned of theResponse) & "." 

JAVASCRIPT 


Open in Script Editor 


Listing 23-2 JavaScript: Prompting for text input 
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var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var response = app.displayDialog("What's your name?", { 
defaultAnswer: "", 
withIcon: "note", 
buttons: ["Cancel", "Continue"], 
defaultButton: "Continue" 
}) 
// Result: {"buttonReturned":"Continue", "textReturned":"Jen"} 


app.displayDialog("Hello, " + (response.textReturned) + ".") 


NOTE 


"with icon 


Additional information about the display dialog command can be found in Displaying Dialogs and Alerts. 
For complete information about the command and its parameters, launch Script Editor, open the Standard 


Additions scripting addition’s dictionary, and navigate to the command's definition. 


Prompting for Hidden Text 


Protect potentially sensitive information from prying eyes by using the display dialog command's default 
answer parameter in conjunction with the hidden answer parameter to show bullets instead of plain text in the 


dialog’s text field. See Figure 23-2, Listing 23-3, and Listing 23-4. 


Figure 23-2 A dialog promoting for hidden text input 


— Please enter a passphrase to use this script. 








APPLESCRIPT 
Open in Script Editor 


Listing 23-3 AppleScript: Prompting for hidden text input 


1 display dialog "Please enter a passphrase to use this script." default answer 
with icon stop buttons {"Cancel", "Continue"} default button "Continue" with 
hidden answer 


2 --> Result: {button returned:"Continue", text returned:"MySecretPassphrase"} 


JAVASCRIPT 
Open in Script Editor 
Listing 23-4 JavaScript: Prompting for hidden text input 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


1 

2 

3 

4 app.displayDialog("Please enter a passphrase to use this script.", { 
5 defaultAnswer: "", 

6 withIcon: "stop", 

7 buttons: ["Cancel", "Continue"], 

8 defaultButton: "Continue", 

9 hiddenAnswer: true 

10 ) 


At // Result: {"buttonReturned":"Continue", "textReturned":"MySecretPassphrase"} 


WARNING 


Always be cautious when requesting sensitive data, such as passwords. Hidden text is returned by the 
display dialog command as plain, unencrypted text, so this command offers limited security. 
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Displaying Notifications 


Notification Center offers another opportunity for providing feedback during script execution. Use the Standard 
Additions scripting addition’s display notification command to show notifications, such as status updates 
as files are processed. Notifications are shown as alerts or banners, depending on the user’s settings in 
System Preferences > Notifications. See Figure 24-1 and Figure 24-2. 


Figure 24-1 A banner notification 


Processing is complete. 


/ My Graphic Processing Script 
All graphics have been converted. 


Figure 24-2 An alert notification 


My Graphic Processing Script Close 
/ Processing is complete. 
All graphics have been converted. Show 


To show a notification, provide the display notification command with a string to display. Optionally, 
provide values for the with title, subtitle, and sound name parameters to provide additional information 
and an audible alert when the notification appears, as shown in Listing 24-1 and Listing 24-2. 


APPLESCRIPT 
Open in Script Editor 
Listing 24-1 AppleScript: Displaying a notification 


display notification "All graphics have been converted." with title "My Graphic 


Processing Script" subtitle "Processing is complete." sound name "Frog" 


JAVASCRIPT 
Open in Script Editor 
Listing 24-2 JavaScript: Displaying a notification 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


1 
2 
3 
4 
5 app.displayNotification("All graphics have been converted.", { 
6 withTitle: "My Graphic Processing Script", 

7 subtitle: "Processing is complete.", 

8 soundName: "Frog" 

9 


}) 


NOTE 
After using a script to display a notification, the script or Script Editor (if the script is run from within Script 
Editor) is added to the list of notifying apps in System Preferences > Notifications. There, you can configure 
options, such as whether to display notifications as alerts or banners. 


Clicking the Show button in an alert-style notification opens the app that displayed the notification. For a 
script app, the action of opening the app again triggers the run handler of the script, potentially causing the 
script to begin processing a second time. Keep this in mind, and add code to your script to handle this 
scenario, if appropriate. 
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Speaking Text 


Spoken text is another way to provide feedback to users during script execution; instead of reading a message 
visually, the user can listen to it audibly. Listing 25-1 and Listing 25-2 show how the Standard Additions 
scripting addition’s say command can be used to speak a phrase. 


APPLESCRIPT 
Open in Script Editor 
Listing 25-1 AppleScript: Speaking text 


say "Processing is complete." 


JAVASCRIPT 
Open in Script Editor 
Listing 25-2 JavaScript: Speaking text 


1 var app = Application. currentApplication() 
2 app.includeStandardAdditions = true 

3 

4 app.say("Processing is complete.") 


The say command has a number of optional parameters, some of which allow you to specify a voice and 
attributes such as speaking rate, pitch, and modulation. See Listing 25-3 and Listing 25-4. 


APPLESCRIPT 
Open in Script Editor 
Listing 25-3 AppleScript: Speaking text with custom speech attributes 


say "Just what do you think you're doing Dave?" using "Alex" speaking rate 14@ pitch 


42 modulation 60 


JAVASCRIPT 
Open in Script Editor 


Listing 25-4 JavaScript: Speaking text with custom speech attributes 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 app.say("Just what do you think you're doing Dave?", { 
5 using: "Alex", 

6 speakingRate: 140, 

7 pitch: 42, 

8 modulation: 60 

9 +) 


Saving Text as an Audio File 


The say command’s saving as parameter adds another level of power, enabling text to be converted to audio 
format and saved as an . aiff file for later listening. This technique could be used, for example, to save email 
messages in audio format, as demonstrated by Listing 25-5 and Listing 25-6. 


APPLESCRIPT 
Open in Script Editor 
Listing 25-5 AppleScript: Saving text as audio 


1 tell application "Mail" 


2 tell message 1 of inbox 
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10 


set theSubject to subject 
set theBody to content 
end tell 
end tell 


set theOutputFile to (path to desktop as string) & "message.aiff" 
set theAudio to "Message Subject: " & theSubject & return & "Body: " & theBody 
say theAudio saving to theOutputFile 


JAVASCRIPT 


Open in Script Editor 


Listing 25-6 JavaScript: Saving text as audio 
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var Mail = Application("Mail") 
var app = Application. currentApplication() 


app.includeStandardAdditions = true 


message = Mail. inbox.messages [@] 
subject = message. subject() 


body = message. content () 


outputFile = ((app.pathTo("desktop").toString()) + "/message.aiff") 
audio = "Message Subject: " + subject + "\nBody: " + body 


app.say(audio, {savingTo: outputFile}) 


Speaking Text While Displaying a Dialog 


Typically, a script executes a single command at a time, waiting for a command to complete before moving 
onto the next. Listing 25-7 and Listing 25-8 demonstrate how to display a dialog message, while 
simultaneously using the NSTask class in the Foundation framework to read the message out loud. 


APPLESCRIPT 


Open in Script Editor 


Listing 25-7 AppleScriptObjC: Speaking text while displaying a dialog 


1 use framework "Foundation" 

2 use scripting additions 

3 

4 set theStatusText to "Processing is complete." 

5 set theTask to (current application's NSTask's 
launchedTaskWithLaunchPath:"/usr/bin/say" arguments: {theStatusText}) 

6 try 

7 display dialog theStatusText 

8 theTask's terminate() 

9 on error 

10 try 

11 theTask's terminate() 

12 end try 

13 end try 

JAVASCRIPT 


Open in Script Editor 


Listing 25-8 JavaScriptObjC: Speaking text while displaying a dialog 


1 
2 
3 
4 


var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var statusText = "Processing is complete." 


var task = $.NSTask. LaunchedTaskWithLaunchPathArguments("/usr/bin/say", 
[statusText] ) 


try { 
app.displayDialog(statusText) 
task. terminate 

t 

catch(error){ 


task. terminate 
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Prompting for Files or Folders 


It’s generally good practice to avoid hard-coding file and folder paths in a script. Prompting the user to select 
files and folders makes for a more dynamic script that won’t break when paths change. 


Prompting for a File 


Use the Standard Additions scripting addition’s choose file command to prompt the user to select a file. 
Listing 26-1 and Listing 26-2 demonstrate how to use this command to display the simple file selection dialog 
with a custom prompt shown in Figure 26-1. 


Figure 26-1 Prompting for a file 


Please select a document to process: 














< 38 Bn S-  l Desktop $ fu} a Q 
iCloud Name Date Modified v 
Faeries ImportantDoc.pages Oct 19, 2015, 11:26 AM 
Devices 
Shared 
Tags 
Media 

Cancel Choose 


APPLESCRIPT 
Open in Script Editor 
Listing 26-1 AppleScript: Prompting for a file 


1 set theDocument to choose file with prompt "Please select a document to process:" 


2 --> Result: alias "Macintosh HD:Users:yourUserName:Documents: ImportantDoc.pages" 


JAVASCRIPT 
Open in Script Editor 
Listing 26-2 JavaScript: Prompting for a file 


var app = Application.currentApplication() 


app.includeStandardAdditions = true 


withPrompt: "Please select a document to process:" 
}) 


1 
2 
3 
4 var document = app.chooseFile({ 
5 
6 
7 document 

8 


// Result: Path("/Users/yourUserName/Documents/ImportantDoc. pages") 


Prompting for a Specific Type of File 


If your script requires specific types of files for processing, you can use the choose file command’s optional 
of type parameter to provide a list of acceptable types. Types may be specified as extension strings without 
the leading period (such as "jpg" or "png") or as uniform type identifiers (such as "public. image" or 
"com.apple. iwork.pages.sffpages"). Listing 26-3 and Listing 26-4 show how to prompt for an image. 


APPLESCRIPT 


Open in Script Editor 


Listing 26-3 AppleScript: Prompting for an image 


1 set theImage to choose file with prompt "Please select an image to process:" of type 


{"public. image"} 


2 --> Result: alias "Macintosh HD:Users:yourUserName: Pictures: IMG_0024. jpg 


JAVASCRIPT 
Open in Script Editor 


Listing 26-4 JavaScript: Prompting for an image 


i var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var image = app.chooseFile({ 

5 withPrompt: "Please select an image to process:", 
6 ofType: ["public. image"] 

7 +) 

8 image 

9 


// Result: Path("/Users/yourUserName/Pictures/IMG_@024. jpg") 


Prompting for Multiple Files 


To let the user choose more than one file, include the choose file command’s optional multiple selections 
allowed parameter. Listing 26-5 and Listing 26-6 display a prompt asking for multiple images, as shown in 
Figure 26-2. 


Figure 26-2 Prompting for multiple images 


Please select some images to process: 














82 Bon %~ @ Pictures $ up =) Q 
iCloud Name Date Modified . 
Favorites By IMG_0024.ipg Oct 19, 2015, 11:26 AM 
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Shared 
Tags 
Media 
Cancel Choose 


APPLESCRIPT 
Open in Script Editor 
Listing 26-5 AppleScript: Prompting for multiple images 


1 set theImages to choose file with prompt "Please select some images to process:" of 
type {"public.image"} with multiple selections allowed 

2 --> Result: {alias "Macintosh HD:Users:yourUserName:Pictures:IMG_0024.jpg", alias 
"Macintosh HD:Users: yourUserName: Pictures: IMG_0025.jpg", alias "Macintosh 


HD: Users: yourUserName: Pictures: IMG_0026.jpg"} 
JAVASCRIPT 
Open in Script Editor 


Listing 26-6 JavaScript: Prompting for multiple images 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var images = app.chooseFile({ 

5 withPrompt: "Please select some images to process:", 

6 ofType: ["public.image"], 

a multipleSelectionsAllowed: true 

8 +) 

9 images 

10 // Result: [Path("/Users/yourUserName/Pictures/IMG_0024.jpg"), 


Path("/Users/yourUserName/Pictures/IMG_0025.jpg"), 
Path("/Users/yourUserName/Pictures/IMG_0026. jpg") ] 


Prompting for a Folder 


Use the Standard Additions scripting addition’s choose folder command to prompt the user to select a folder, 
such as an output folder or folder of images to process. Listing 26-7 and Listing 26-8 demonstrate how to use 
this command to display the simple folder selection dialog with a custom prompt shown in Figure 26-3. 


Figure 26-3 Prompting for a folder 


Please select an output folder: 
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APPLESCRIPT 
Open in Script Editor 
Listing 26-7 AppleScript: Prompting for a folder 


1 set theOutputFolder to choose folder with prompt "Please select an output folder:" 


2 --> Result: alias "Macintosh HD:Users:yourUserName:Desktop:" 
JAVASCRIPT 


Open in Script Editor 


Listing 26-8 JavaScript: Prompting for a folder 


a var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var outputFolder = app.chooseFolder({ 

5 withPrompt: "Please select an output folder:" 
6 +) 

7 outputFolder 

8 


// Result: Path("/Users/yourUserName/Desktop") 


Prompting for Multiple Folders 


To let the user choose more than one folder, include the choose folder command’s optional multiple 
selections allowed parameter, as shown in Listing 26-9 and Listing 26-10. 


APPLESCRIPT 
Open in Script Editor 
Listing 26-9 AppleScript: Prompting for multiple folders 


1 set theFoldersToProcess to choose folder with prompt "Please select the folders 


containing images to process:" with multiple selections allowed 


2 --> Result: {alias "Macintosh HD:Users:yourUserName:Desktop:", alias "Macintosh 


HD: Users: yourUserName:Documents:"} 


JAVASCRIPT 
Open in Script Editor 


Listing 26-10 JavaScript: Prompting for multiple folders 


a var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var foldersToProcess = app.chooseFolder({ 

5 withPrompt: "Please select an output folder:", 
6 multipleSelectionsAllowed: true 

7 +) 

8 foldersToProcess 

9 


// Result: [Path("/Users/yourUserName/Desktop"), 


Path("/Users/yourUserName/Documents") ] 


Terms of Use | Privacy Policy | Updated: 2016-06-13 


Prompting for a File Name 


Use the Standard Additions scripting addition’s choose file name command to display a save dialog that lets 
the user enter a file name and choose an output folder, such as the one produced by Listing 27-1 and Listing 
27-2, shown in Figure 27-1. 


Figure 27-1 Prompting for a file name 


Choose File Name 


Save the document as: 


Save As: ImportantDocument| v 


Tags: 
Where: |) Desktop 





APPLESCRIPT 
Open in Script Editor 
Listing 27-1 AppleScript: Prompting for a file name 


1 set theNewFilePath to choose file name with prompt "Save the document as:" 


2 --> Result: file "Macintosh HD:Users: yourUserName: Desktop: ImportantDocument" 


JAVASCRIPT 
Open in Script Editor 


Listing 27-2 JavaScript: Prompting for a file name 


1 var app = Application. currentApplication() 
2 app.includeStandardAdditions = true 

3 

4 var newFilePath = app.chooseFileName({ 

5 withPrompt: "Save the document as:" 

6 }) 

7 newFilePath 

8 


// Result: Path("/Users/yourUserName/Desktop/ImportantDocument") 


If the specified file name already exists in the output folder when the user clicks the Save button, the user is 
prompted to replace it, as shown in Figure 27-2. 


Figure 27-2 Prompting to replace an existing file 


A file or folder with the same name already exists on 
the Desktop. Replacing it will overwrite its current 
contents. 


“ImportantDocument” already exists. Do 
a, you want to replace it? 


The result of the choose file name command is a path to a potential file. This file may or may not already 
exist. However, if it does exist, you can assume the user wants to replace it. Your script can now safely write 
or save a file to the path. 


Listing 27-3 and Listing 27-4 ask the user to type some text as a note and choose an file name and output 
folder, and then save the note in the specified file. 


APPLESCRIPT 
Open in Script Editor 


Listing 27-3 AppleScript: Saving content in a specified file 





1 set theResponse to display dialog "Enter a note:" default answer '"'" 
2 set theNote to text returned of theResponse 
3 
4 set theNewFilePath to choose file name with prompt "Save the document as:" 
5 
6 writeTextToFile(theNote, theNewFilePath, true) 
7 
8 on writeTextToFile(theText, theFile, overwriteExistingContent) 
9 try 
10 
11 -- Convert file to a string 
12 set theFile to theFile as string 
13 
14 -- Open file for writing 
15 set theOpenedFile to open for access file theFile with write permission 
16 
17 -- Clear file if content should be overwritten 
18 if overwriteExistingContent is true then set eof of theOpenedFile to 0 
19 
20 -- Write new content to file 
21 write theText to theOpenedFile starting at eof 
22 
23 =——- Close file 
24 close access theOpenedFile 
25 
26 -- Return a boolean indicating that writing was successful 
27 return true 
28 
29 -- Handle a write error 
30 on error 
31 
32 = Close file 
33 try 
34 close access file theFile 
35 end try 
36 
37 -- Return a boolean indicating that writing failed 
38 return false 
39 end try 
40 end writeTextToFile 
JAVASCRIPT 


Open in Script Editor 
Listing 27-4 JavaScript: Saving content in a specified file 


var app = Application. currentApplication() 


app. includeStandardAdditions = true 


var response = app.displayDialog("Enter a note:", { 


defaultAnswer: 


t) 


var note = response. textReturned 
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var newFilePath = app.chooseFileName({ 
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withPrompt: "Save document as:" 
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writeTextToFile(note, newFilePath, true) 


function writeTextToFile(text, file, overwriteExistingContent) { 


}) 


try { 


// Convert file to a string 


var fileString = 


// Open file for 


var openedFile = 


// Clear file if 


file. toString() 


writing 


app.openForAccess(Path(fileString), { writePermission: true 


content should be overwritten 


if (overwriteExistingContent) { 


app.setEof(openedFile, { to: @ }) 


// Write new content to file 


app.write(text, { to: openedFile, startingAt: app.getEof(openedFile) }) 


// Close file 


app.closeAccess (openedFile) 


// Return a boolean indicating that writing was successful 


return true 


t 


catch (error) { 


try { 


// Close file 


app.closeAccess (file) 


} 


catch(error) { 


// Report error is closing failed 


console. log(~ 


// Return a boolean indicating that writing was successful 


return false 


Couldn't close file: ${error}* ) 
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Prompting for a Choice from a List 


Use the Standard Additions scripting addition’s choose from list command to prompt the user to select from 
a list of strings. Listing 28-1 and Listing 28-2 ask the user to select a favorite fruit, as seen in Figure 28-1. 


Figure 28-1 Prompting the user to choose from a list of items 


Select your favorite fruit: 


Banana 
Orange 





APPLESCRIPT 
Open in Script Editor 
Listing 28-1 AppleScript: Prompting the user to choose from a list of items 


1 set theFruitChoices to {"Apple", "Banana", "Orange"} 

2 set theFavoriteFruit to choose from list theFruitChoices with prompt "Select your 
favorite fruit:" default items {"Apple"} 

3 theFavoriteFruit 


4 --> Result: {"Apple"} 


JAVASCRIPT 
Open in Script Editor 


Listing 28-2 JavaScript: Prompting the user to choose from a list of items 


1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var fruitChoices = ["Apple", "Banana", "Orange"] 

5 var favoriteFruit = app.chooseFromList(fruitChoices, { 
6 withPrompt: "Select your favorite fruit:", 

7 defaultItems: ["Apple"'] 

8 +) 

9 favoriteFruit 

10 // Result: ["Apple"] 


The choose from list command can optionally let the user choose multiple items by setting the multiple 
selections allowed parameter to true. For this reason, the result of the command is always a list of selected 
strings. This list may be empty if the empty selection allowed parameter has been specified and the user 
dismissed the dialog without making a selection. 
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Prompting for a Color 


Use the Standard Additions scripting addition’s choose color command to ask the user to select a color from 
a color picker dialog like the one shown in Figure 29-1. The command accepts an optional default color 
parameter, and produces an RGB color value as its result. Listing 29-1 and Listing 29-2 display a color picker, 
create a TextEdit document containing some text, and apply the chosen color to the text. 


Figure 29-1 A color picker dialog 
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APPLESCRIPT 
Open in Script Editor 


Listing 29-1 AppleScript: Adding colored text to a new TextEdit document 


1 set theColor to choose color default color {@, 65535, 0} 
2 --> Result: {256, 40421, 398} 

3 

4 tell application "TextEdit" 

5 set theDocument to make new document 

6 set text of document 1 to "Colored Text" 

Fi set color of text of document 1 to theColor 

8 end tell 

JAVASCRIPT 


Open in Script Editor 

Listing 29-2 JavaScript: Adding colored text to a new TextEdit document 

1 var app = Application. currentApplication() 

2 app.includeStandardAdditions = true 

3 

4 var color = app.chooseColor({defaultColor: [@, 1, ]}) 

5 // Result: [0.003753719385713339, @.7206835746765137, @.005828946363180876] 
6 
7 


color = [Math.trunc(color[@] * 65535), Math.trunc(color[1] * 65535), 
Math.trunc(color[2] * 65535)] 


9 var textedit = Application("TextEdit") 

10 var document = textedit.make({new: "document"}) 
it document.text = "Colored Text" 

12 document.text.color = [256, 40421, 398] 


NOTE 


In AppleScript, the choose color command produces RGB values ranging from @ through 65535. In 
JavaScript, the RGB values range between @ and 1. These values must be converted to match the 


AppleScripi vaiues io be used. Listing 25-2 demonsiraies inis conversion. 
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Displaying Progress 


Many scripts perform large and time-consuming processing operations. All too often, they do this invisibly; 
they simply run and the user has no idea how long processing will take. A more user-friendly approach is to 
provide progress information during script operation. At a basic level, this can be done by displaying periodic 
dialogs or notifications. See Displaying Dialogs and Alerts and Displaying Notifications. At a complex level, this 
can be done by designing a fully-custom interface that provides processing feedback. 


AppleScript and JavaScript can also report progress graphically and textually. For script apps, this progress 
reporting takes the form of a dialog window containing a progress bar, descriptive text, and a Stop button. See 
Figure 30-1. 


Figure 30-1 A script progress dialog 


e@ Progress Example 


Processing Images... 
Processing image 1 of 3 


SSeS Stop 


For scripts running in Script Editor, this progress reporting appears at the bottom of the script window. See 
Figure 30-2. 


Figure 30-2 Progress displayed in Script Editor 


Running... 





@ Processing Images... (Processing image 2 of 3) 
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For scripts running from the systemwide script menu, this progress reporting appears in the menu bar, 
beneath a temporarily displayed gear icon. See Figure 30-3. 


Figure 30-3 Progress of a script menu script 
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AppleScript has several language-level properties and JavaScript has a Progress object with properties that 
are used to produce this type of progress reporting. See Table 30-1. 


Table 30-1 Progress properties in AppleScript and JavaScript 


AppleScript Property JavaScript Property Value Description 
Type 


AppleScript Property 


progress total steps 


progress completed 


steps 


progress description 


progress additional 


description 


JavaScript Property 


Progress. totalUnitCou 
nt 


Progress.completedUni 
tCount 


Progress.description 


Progress.additionalDe 


scription 


Value 
Type 


Integer 


Integer 


Integer 


Integer 


Description 


Configures the total number 





of steps to be reported in 
the progress. For example, 
if the script will process 5 
images, then the value for 
progress total steps 
would be 5. 


Configures the number of 
steps completed so far. For 
example, if the script has 
processed 3 of 5 images, 
then the value of progress 
completed steps would be 
3. 


Text to display when 
reporting progress. Use this 
is an opportunity to let the 
user know what’s 
happening. For example, it 
could indicate that images 
are being processed. 


Additional text to display 
when reporting progress. 
Use this is an opportunity to 
provide even more detailed 
information about what’s 
happening. For example, it 
could indicate the specific 
task being performed, and 
how much more processing 
is remaining. 


Listing 30-1 and Listing 30-2 demonstrate how these properties can be used to provide progress information 


while processing a set of images. 


APPLESCRIPT 


Open in Script Editor 


Listing 30-1 AppleScript: Display progress while processing images 


1 set theImages to choose file with prompt "Please select some images to process:" of 


type {"public.image"} with multiple selections allowed 


2 

3 -- Update the initial progress information 

4 set theImageCount to length of theImages 

5 set progress total steps to theImageCount 

6 set progress completed steps to 0 

7 set progress description to "Processing Images..." 

8 set progress additional description to "Preparing to process." 

9 

10 repeat with a from 1 to length of theImages 

11 

12 -- Update the progress detail 

13 set progress additional description to "Processing image" &a&" of "& 
theImageCount 

14 

15 -- Process the image 

16 

17 -- Increment the progress 

18 set progress completed steps to a 





20 


-- Pause for demonstration purposes, so progress can be seen 


21 delay 1 

22 end repeat 

23 

24 -- Reset the progress information 

25 set progress total steps to @ 

26 set progress completed steps to 0 

27 set progress description to "" 

28 set progress additional description to "" 
JAVASCRIPT 


Open in Script Editor 


Listing 30-2 JavaScript: Display progress while processing images 


ry 


ry 


PrP Oo oO ON DUN BP WY BR 


12 





var app = Application. currentApplication() 


app.includeStandardAdditions = true 


var images = app.chooseFile({ 


}) 


withPrompt: "Please select some images to process:", 
ofType: ["public.image"], 


multipleSelectionsAllowed: true 


// Update the initial progress information 


var imageCount = images. length 


Progress.totalUnitCount = imageCount 


Progress.completedUnitCount = @ 


Progress.description = "Processing Images..." 


Progress.additionalDescription = "Preparing to process." 


fo 


r (i = @; i < imageCount; i++) { 
// Update the progress detail 


Progress.additionalDescription = "Processing image " + i+" of " + imageCount 


// Process the image 


// Increment the progress 


Progress.completedUnitCount = i 


// Pause for demonstration purposes, so progress can be seen 
delay(1) 


Clicking the Stop button in a progress dialog results in a user cancelled error. 


For additional information, see Progress Reporting in AppleScript Release Notes and Progress in JavaScript 
for Automation Release Notes. 


NOTE 


There’s no need to call a dedicated command to actually display progress information. The act of setting 
values for the progress properties mentioned above automatically results in progress information being 
displayed in a dialog, Script Editor, or the menu bar. 
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Converting RGB to HTML Color 


In HTML documents, colors are typically represented as hex values. The handlers in Listing 31-1 and Listing 
31-2 show how to convert 8-bit or 256 color-based RGB values to hex values. Provide an RGB color 
represented by a list of three numbers, each with a value between @ and 65535. 


APPLESCRIPT 
Open in Script Editor 
Listing 31-1 AppleScript: Handler that converts an RGB color to a hex value 


1 on convertRGBColorToHexVa lue(theRGBVa Lues ) 
2 set theHexList to {"o", co Th mM, a ae mqre eae "on. iy ae i saa bt Lia AN "B", 
ae ChE bl Daa "EM. sh SA 


3 set theHexValue to "" 

4 repeat with a from 1 to count of theRGBValues 

5 set theCurrentRGBValue to (item a of theRGBValues) div 256 

6 if theCurrentRGBValue is 256 then set theCurrentRGBValue to 255 

7 set theFirstItem to item ((theCurrentRGBValue div 16) + 1) of theHexList 

8 set theSecondItem to item (((theCurrentRGBValue / 16 mod 1) * 16) + 1) of 

theHexList 

9 set theHexValue to (theHexValue & theFirstItem & theSecondItem) as string 
10 end repeat 
11 return ("#" & theHexValue) as string 


12 end convertRGBColorToHexValue 


JAVASCRIPT 
Open in Script Editor 


Listing 31-2 JavaScript: Function that converts an RGB color to a hex value 





i function convertRGBColorToHexValue(rgbValues) { 

2 var r = parseInt(rgbValues[0], 10).toString(16).slice(-2) 
3 if (r.length == 1) 

4 r= "Q" 46 

5 var g = parseInt(rgbValues[1], 10).toString(16).slice(-2) 
6 if (g.length == 1) 

7 g= "0" +g 

8 var b = parseInt(rgbValues[2], 10).toString(16).slice(-2) 
9 if (b. length == 1) 

10 b= "0" +b 

11 return ("#" + r +g + b) 

12 + 


Listing 31-3 shows how to call the handlers in Listing 31-1 to convert a specified RGB color to a hex value for 
use in HTML. 


APPLESCRIPT 
Open in Script Editor 
Listing 31-3 AppleScript: Calling a handler to convert an RGB color to a hex value 


1 set theRGBValues to (choose color default color {65535, 0, @}) 
2 convertRGBColorToHexVa Lue ( theRGBVa Lues ) 
3 --> Result: "#FFQQ00" 


JAVASCRIPT 
Open in Script Editor 
Listing 31-4 JavaScript: Calling a function to convert an RGB color to a hex value 


1 var app = Application. currentApplication() 


un B&B WN 
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app.includeStandardAdditions = true 


var color = app.chooseColor({defaultColor: [1, 0, ]}) 

color = [Math.trunc(color[@] * 65535), Math.trunc(color[1] * 65535), 
Math. trunc(color[2] * 65535) ] 

convertRGBColorToHexValue(color) 

// Result: "#FFQ000" 


NOTE 


In AppleScript, the choose color command produces RGB values ranging from @ through 65535. In 
JavaScript, the RGB values range between @ and 1. These values must be converted to match the 
AppleScript values to be used. Listing 31-4 demonstrates this conversion. 
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Encoding and Decoding Text 


A standard practice when creating URL's is to encode spaces and special characters (high-level ASCII) to 
hexadecimal equivalents. For example, spaces in URL's are routinely converted to =20. The process of 
encoding and decoding URLs and other text in this manner can be accomplished through scripting. 


Encoding Characters 

The handler in Listing 32-1 encodes a single character. 
APPLESCRIPT 

Open in Script Editor 

Listing 32-1 AppleScript: Handler that URL encodes a character 


1 on encodeCharacter(theCharacter) 
2 set theASCIINumber to (the ASCII number theCharacter) 
3 set theHexList to {"o", "1", "2", "3", "4", "5", "6", "7", "BN, "ON, MAN, "BM, 
wit omp MEN, MEM} 
set theFirstItem to item ((theASCIINumber div 16) + 1) of theHexList 
set theSecondItem to item ((theASCIINumber mod 16) + 1) of theHexList 
return ("%'" & theFirstItem & theSecondItem) as string 


nN oO Ww ff 


end encodeCharacter 


Listing 32-2 shows how to call the handler in Listing 32-1. 
APPLESCRIPT 

Open in Script Editor 

Listing 32-2 AppleScript: Calling a handler to URL encode a character 


1 encodeCharacter("$") 


2 --> Result: "%24" 


Encoding Text 


The handler in Listing 32-3 encodes an entire string. Provide a string and indicate whether to encode two 
levels of special characters. The first level includes commonly encoded special characters, such as $, %, and 
*. The second level includes extended special characters that aren’t typically encoded—., -, _, and :. High- 
level ASCII characters, such as copyright symbols, trademark symbols, and spaces, are always encoded. 


APPLESCRIPT 
Open in Script Editor 
Listing 32-3 AppleScript: Handler that URL encodes text 


1 on encodeText(theText, encodeCommonSpecialCharacters, 
encodeExtendedSpecialCharacters) 
set theStandardCharacters to “abcdefghijklmnopqrstuvwxyz0123456789" 
set theCommonSpecialCharacterList to "$+!'/?;&@=#%><{}\"~ "> ™\\ [*" 


set theExtendedSpecialCharacterList to ".—_: 


set theAcceptableCharacters to theStandardCharacters 


ao wu & WwW N 


if encodeCommonSpecialCharacters is false then set theAcceptableCharacters to 
theAcceptableCharacters & theCommonSpecialCharacterList 
7 if encodeExtendedSpecialCharacters is false then set theAcceptableCharacters to 
theAcceptableCharacters & theExtendedSpecialCharacterList 
8 set theEncodedText to "" 
9 repeat with theCurrentCharacter in theText 


10 if theCurrentCharacter is in theAcceptableCharacters then 


11 set theEncodedText to (theEncodedText & theCurrentCharacter) 
12 else 
13 set theEncodedText to (theEncodedText & 


encodeCharacter(theCurrentCharacter)) as string 





14 end if 
15 end repeat 
16 return theEncodedText 
17 end encodeText 


NOTE 


This handler calls the encodeCharacter() handler. See Listing 32-1. 


Listing 32-4 shows how to call the handler in Listing 32-3 to encode only high-level ASCII characters. 
APPLESCRIPT 

Open in Script Editor 

Listing 32-4 AppleScript: Calling a handler to URL encode high-level ASCII characters in text 


1 encodeText ("*smith-wilson© report_23.txt", false, false) 


2 --> Result: "xsmith-wilson%A9%2@report_23.txt" 


Listing 32-5 shows how to call the handler in Listing 32-3 to encode high-level ASCII characters and all special 
characters. 


APPLESCRIPT 
Open in Script Editor 
Listing 32-5 AppleScript: Calling a handler to URL encode high- and low-level ASCII characters in text 


1 encodeText("*smith-wilson© report_23.txt", true, true) 


2 --> Result: "%2Asmith%2Dwilson%A9%2@report%5F23%2Etxt" 


Listing 32-6 shows how to call the handler in Listing 32-3 to encode high-level ASCII characters and special 
characters, excluding periods, hyphens, underscores, and colons. 


APPLESCRIPT 
Open in Script Editor 
Listing 32-6 AppleScript: Calling a handler to URL encode high- and low-level ASCII characters in text with certain exclusions 


1 encodeText ("annual smith-wilson_report.txt", true, false) 


2 --> Result: "annual%*2Q@smith-wilson_report.txt" 


NOTE 


When you use AppleScriptObjC, you can use methods of the NSSt ring class to encode text. The handler in 
Listing 32-7 demonstrates how to do this. 


APPLESCRIPT 
Open in Script Editor 


Listing 32-7 AppleScriptObjC: Handler that URL encodes text 


1 on encodeText(theText) 


2 set theString to stringWithString_(theText) of NSString of current 
application 

3 set theEncoding to NSUTF8StringEncoding of current application 

4 set theAdjustedString to 


stringByAddingPercentEscapesUsingEncoding_(theEncoding) of theString 
5) return (theAdjustedString as string) 
6 end encodeText 


Decoding Text 

The handler in Listing 32-8 decodes an encoded character hex string. 
APPLESCRIPT 

Open in Script Editor 

Listing 32-8 AppleScript: Handler that decodes an encoded character hex string 


1 on decodeCharacterHexString(theCharacters) 
2 copy theCharacters to {theIdentifyingCharacter, theMultiplierCharacter, 


theRemainderCharacter} 


3 set theHexList to '"123456789ABCDEF" 
4 if theMultiplierCharacter is in "ABCDEF" then 
5 set theMultiplierAmount to offset of theMultiplierCharacter in theHexList 
6 else 
7 set theMultiplierAmount to theMultiplierCharacter as integer 
8 end if 
9 if theRemainderCharacter is in "ABCDEF" then 
10 set theRemainderAmount to offset of theRemainderCharacter in theHexList 
11 else 
12 set theRemainderAmount to theRemainderCharacter as integer 
13 end if 
14 set theASCIINumber to (theMultiplierAmount * 16) + theRemainderAmount 
15 return (ASCII character theASCIINumber) 
16 end decodeCharacterHexString 





Listing 32-9 shows how to call the handler in Listing 32-8. 
APPLESCRIPT 

Open in Script Editor 

Listing 32-9 AppleScript: Calling a handler to decode an encoded character hex string 


1 decodeCharacterHexSt ring("%24") 
2 --> Result: "$" 


The handler in Listing 32-10 decodes any encoded character hex strings in the specified text. 
APPLESCRIPT 

Open in Script Editor 

Listing 32-10 AppleScript: Handler that decodes any encoded character hex strings in specified text 


on decodeText(theText) 
set flagA to false 
set flagB to false 


set theTempCharacter to 
set theCharacterList to {} 
repeat with theCurrentCharacter in theText 


set theCurrentCharacter to contents of theCurrentCharacter 


set flagA to true 


else if flagA is true then 


set theTempCharacter to theCurrentCharacter 


set flagA to false 


set flagB to true 


else if flagB is true then 


1 
2 
3 
4 
5 
6 
7 
8 if theCurrentCharacter is "%" then 
9 
1) 
1 
2 
3 
4 
5 


set end of theCharacterList to decodeCharacterHexString(("%" & 
theTempCharacter & theCurrentCharacter) as string) 

set theTempCharacter to "" 
set flagA to false 


6 
7 
18 set flagB to false 
9 





else 


20 set end of theCharacterList to theCurrentCharacter 
21 end if 

22 end repeat 

23 return theCharacterList as string 


24 end decodeText 


NOTE 


This handler calls the decodeCharacterHexString() handler. See Listing 32-8. 


Listing 32-11 shows how to call the handler in Listing 32-10. 

APPLESCRIPT 

Open in Script Editor 

Listing 32-11 AppleScript: Calling a handler to decode any encoded character hex strings in specified text 


1 decodeText ("%2Asmith%2Dwilson%A9%20report%5F23%2Etxt" ) 


2 --> Result: "xsmith-wilson© report_23.txt" 


NOTE 

When you use AppleScriptObjC, you can use methods of the NSSt ring class to decode URL encoded text. 
The handler in Listing 32-12 demonstrates how to do this. 

APPLESCRIPT 


Open in Script Editor 


Listing 32-12 AppleScriptObjC: Handler that decodes URL encoded text 


on decodeText (theText) 
2 set theString to stringwWithString_(theText) of NSString of current 
application 
set theEncoding to NSUTF8StringEncoding of current application 
4 set theAdjustedString to 
stringByReplacingPercentEscapesUsingEncoding_(theEncoding) of theString 
return (theAdjustedString as string) 
end decodeText 
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Parsing HTML 


The process of reading an HTML file is no different than the process of reading a standard text file—see 
Reading a File to learn how to do it. However, it’s often necessary to extract specific bits of information from 
HTML files, such as links, images, and table data, for further processing. 


Parsing an HTML File 


The handler in Listing 33-1 extracts specific tags and their content from HTML text. Provide an HTML file to 
read, a closing and ending tag, and indicate whether to return only content between the tags, or the tags with 
their enclosed content. If no closing tag is provided, the handler extracts the opening tag data only. This 
feature could be used to extract image tags from HTML content, for example, which don’t have a separate 
closing tag. 


APPLESCRIPT 
Open in Script Editor 


Listing 33-1 AppleScript: Handler that parses an HTML file for specific tagged content 


1 on parseHTMLFile(theFile, theOpeningTag, theClosingTag, returnContentsOnly) 

2 try 

3 set theFile to theFile as string 

4 set theFile to open for access file theFile 

5 set theCombinedResults to "" 

6 set theCurrentOpeningTag to "" 

7 repeat 

8 read theFile before "<" 

9 set theCurrentTag to read theFile until ">" 
10 if theCurrentTag does not start with "<" then set theCurrentTag to ("<" 


& theCurrentTag) as string 





11 if theCurrentTag begins with theOpeningTag then 

12 set theCurrentOpeningTag to theCurrentTag 

13 if theClosingTag is "" then 

14 if theCombinedResults is "" then 

15 set theCombinedResults to theCombinedResults & 
theCurrentOpeningTag 

16 else 

17 set theCombinedResults to theCombinedResults & return & 
theCurrentOpeningTag 

18 end if 

19 else 

20 set theTextBuffer to "" 

21 repeat 

22 set theTextBuffer to theTextBuffer & (read theFile before " 
<") 

23 set theTagBuffer to read theFile until ">" 

24 if theTagBuffer does not start with "<" then set 
theTagBuffer to ("<" & theTagBuffer) 

25 if theTagBuffer is theClosingTag then 

26 if returnContentsOnly is false then 

27 set theTextBuffer to theCurrentOpeningTag & 
theTextBuffer & theTagBuffer 

28 end if 

29 if theCombinedResults is "" then 

30 set theCombinedResults to theCombinedResults & 
theTextBuf fer 


31 else 


32 set theCombinedResults to theCombinedResults & 
return & theTextBuffer 


33 end if 

34 exit repeat 

35 else 

36 set theTextBuffer to theTextBuffer & theTagBuffer 
aT end if 

38 end repeat 

39 end if 

40 end if 

41 end repeat 

42 close access theFile 

43 on error theErrorMessage number theErrorNumber 

44 try 

45 close access theFile 

46 end try 

47 if theErrorNumber is not -39 then return false 
48 end try 

49 return theCombinedResults 





ul 
Ss 


end parseHTMLFile 


Listing 33-2 shows how to call the handler in Listing 33-1 to extract all hyperlinks within a chosen HTML file. 
APPLESCRIPT 

Open in Script Editor 

Listing 33-2 AppleScript: Calling a handler to parse an HTML file for URLs 


1 set theFile to choose file with prompt "Select an HTML file:" 


2 parseHTMLFile(theFile, "<A HREF=", "</A>", false) 
3 --> Example of Result: "<A HREF="http://www.apple.com/fileA.html">Click here to view 
fileA.</A> 


4 <A HREF="http://www.apple.com/fileB.html">Click here to view fileB.</A>" 


Listing 33-3 shows how to call the handler in Listing 33-1 to extract the destinations of all hyperlinks within a 
chosen HTML file. 


APPLESCRIPT 
Open in Script Editor 
Listing 33-3 AppleScript: Calling a handler to parse an HTML file for URLs 


set theFile to choose file with prompt "Select an HTML file:" 
parseHTMLFile(theFile, "<A HREF=", "</A>", true) 


--> Example of Result: "Click here to view fileA. 


BR WN BR 


Click here to view fileB." 


Listing 33-4 shows how to call the handler in Listing 33-1 to extract all images within a chosen HTML file. 
APPLESCRIPT 

Open in Script Editor 

Listing 33-4 AppleScript: Calling a handler to parse an HTML file for images 


1 set theFile to choose file with prompt "Select an HTML file:" 

2 parseHTMLFile(theFile, "<IMG ", "", false) 

3 --> Example of Result: "<IMG SRC="gfx/clipboard.gif" BORDER="0"> 

4 <IMG SRC="printer_stopped.gif" ALIGN=TOP WIDTH="32" HEIGHT="32" BORDER="0"> 
5 <IMG SRC="printer_on.gif" ALIGN=TOP WIDTH="32" HEIGHT="32" BORDER="0">" 


Listing 33-5 shows how to call the handler in Listing 33-1 to extract any tables within a file. 
APPLESCRIPT 


Open in Script Editor 


Listing 33-5 AppleScript: Calling a handler to parse an HTML file for tables 


1 set theFile to choose file with prompt "Select an HTML file:" 
2 parseHTMLFile(theFile, "<TABLE", "</TABLE>", false) 

3 --> Example of Result:"<TABLE WIDTH="440"> 

4 <TR> 

5 <TD ALIGN="CENTER" VALIGN="TOP"> 

6 <IMG SRC="gfx/clipboard.gif" BORDER="0"> 

7 </TD> 

8 </TR> 

9 </TABLE>" 


Parsing an HTML Tag 


The handler in Listing 33-6 extracts the contents —first instance of text contained within quotes—of an HTML 
tag. 


APPLESCRIPT 
Open in Script Editor 


Listing 33-6 AppleScript: Handler that parses an HTML tag for content 


1 on parseHTMLTag(theHTMLTag) 

2 set AppleScript's text item delimiters to "\"" 

3 set theHTMLTagElements to text items of theHTMLTag 

4 set AppleScript's text item delimiters to "" 

5 if length of theHTMLTagElements is greater than 1 then return item 2 of 
theHTMLTagE lements 

6 return "" 


7 end parseHTMLTag 


Listing 33-7 shows how to call the handler in Listing 33-6 to extract the destination of a hyperlink tag. 
APPLESCRIPT 

Open in Script Editor 

Listing 33-7 AppleScript: Calling a handler to parse an HTML tag for content 


1 set theHTMLTag to "<A HREF=\"http://www.apple.com/fileA.html\">Click here to view 
fileA.</A>" 

2 parseHTMLTag(theHTMLTag) 

3 --> Result: "http://www.apple.com/fileA. html" 
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Removing HTML Markup from Text 


When parsing HTML content, it’s often necessary to remove markup entirely. The handler in Listing 34-1 
removes all HTML tags from the text provided, returning only the remaining text—the contents of the tags. 


APPLESCRIPT 
Open in Script Editor 
Listing 34-1 AppleScript: Handler that removes HTML markup from text 


on removeMarkupFromText (theText) 
set tagDetected to false 
set theCleanText to "" 
repeat with a from 1 to length of theText 
if theCurrentCharacter is "<" then 
set tagDetected to true 


else if theCurrentCharacter is ">" then 


1 
2 
3 
4 
5 set theCurrentCharacter to character a of theText 
6 
7 
8 
9 set tagDetected to false 
10 else if tagDetected is false then 
11 set theCleanText to theCleanText & theCurrentCharacter as string 
12 end if 
13 end repeat 
14 return theCleanText 


15 end removeMarkupFromText 


Listing 34-2 shows how to call the handler in Listing 34-1. 
APPLESCRIPT 

Open in Script Editor 

Listing 34-2 AppleScript: Calling a handler to remove HTML markup from text 


1 set theText to "<a href=\"http://ww.apple.com/mac\">This is a <B>great</B> time to 
own a Mac!</a>" 
2 removeMarkupFromText (theText) 


3 --> Result: "This is a great time to own a Mac!" 
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Working with Property List Files 


Many apps store settings in property list files (also called plists). Scripts can also store and retrieve data in 
plists. The terminology for interacting with plists is found in the Property List Suite of the System Events 
scripting dictionary (see Figure 35-1). 


Figure 35-1 Property list terminology in the System Events scripting dictionary 






eee © System Events 
< AA (Z aS AppleScript ay tf Q Terminology 
Back/Forward Text Size View Language Print Search 
[-) Login items suite > application rs 
Network Preferences Suite > f 
(5) Screen Saver Suite > [a property list item r 


{5) Audio File Suite 

{) Security Suite 
Disk-Folder-File Suite 
Folder Actions Suite 
{5) Movie File Suite 

(5) Power Suite 

(5) Processes Suite 

{5) Property List Suite 
(5) QuickTime File Suite 
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(5) Type Definitions 
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property list file n [inh. file] : A file containing data in Property List format 


ELEMENTS 
contained by application. 


PROPERTIES 
(property list item) : the contents of the property list file; elements and properties of the property list item may be accessed as if 
they were elements and properties of the property list file 


property list item n : A unit of data in Property List format 


ELEMENTS 

contains property list items; contained by application, property list items. 

PROPERTIES 

kind (type, r/o) : the kind of data stored in the property list item: boolean/data/date/list/number/record/string 
name (text, r/o) : the name of the property list item ( if any ) 

text (text) : the text representation of the property list data 

value (number, boolean, date, list, record, text, or data) : the value of the property list item 


Creating a New Property List File 


Listing 35-1 demonstrates how to create a new property list file. First, an empty plist file (class property list 
file) is created. Next, individual property list items (class property list item) of varying type (Boolean, 
date, list, number, record, string) are added to the file. 


APPLESCRIPT 
Open in Script Editor 


Listing 35-1 AppleScript: Creating a property list file 


1 tell application "System Events" 

2 -- Create an empty property list dictionary item 

3 set theParentDictionary to make new property list item with properties 
{kind: record} 

4 

5 -- Create a new property list file using the empty dictionary list item as 
contents 

6 set thePropertyListFilePath to "~/Desktop/Example.plist" 

7 

8 set thePropertyListFile to make new property list file with properties 
{contents:theParentDictionary, name:thePropertyListFilePath} 

9 

10 -- Add a Boolean key 


TT. tell property list items of thePropertyListFile 





28 
29 


name: 


name: 


name: 


name: 


name: 


name: 


end 


make new property list item at 


“booleanKey", value: true} 


-- Add a date key 
make new property list item at 


dateKey", value:current date} 


-- Add a list key 
make new property list item at 


"ListKey"} 


-- Add a number key 
make new property list item at 


numberKey", value:5} 


-- Add a record/dictionary key 
make new property list item at 


“recordKey"} 


-- Add a string key 


make new property list item at 


end 


end 


end 


end 


end 


end 


“stringKey", value:"string value"} 


tell 


end tell 


with properties {kind: 


with properties {kind: 


with properties {kind: 


with properties {kind: 


with properties {kind: 


with properties {kind: 


boolean, 


date, 


list, 


number, 


record, 


string, 


Listing 35-2 shows the contents of a property list file created by the script in Listing 35-1. 


Listing 35-2 Example XML for a property list file created by a script 





<?xml version="1.0" encoding="UTF-8" ?> 
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" 
“http: //www.apple.com/DTDs/PropertyList-1.0.dtd"> 


<plist version="1.0"> 


<dict> 


<key>boo LeanKey</key> 


<true/> 


<key>dateKey</key> 


<date>2016-01-28T19:34:13Z</date> 


<key>ListKey</key> 


<array/> 


<key>numberKey</key> 


<integer>5</integer> 


<key>recordKey</key> 


<dict/> 


<key>stringKey</key> 


<string>string value</string> 


</dict> 


</plist> 


Reading a Property List Key Value 


Listing 35-3 shows how to read a value of a key in a property list file. 


Open in Script Editor 


Listing 35-3 AppleScript: Reading a key value in a property list file 


1 
2 
3 
4 
5 


tell application "System Events" 


tell property list file thePropertyListFilePath 


return value of property list item "stringKey" 


end tell 
end tell 


6 --> Result: "string value" 


Changing a Property List Key Value 
Listing 35-4 shows how to change the value of a key in a property list file. 
Open in Script Editor 
Listing 35-4 AppleScript: Changing the value of a key in a property list file 
tell application "System Events" 


tell property list file thePropertyListFilePath 


1 
2 
3 set value of property list item "stringKey" to "new string value" 
4 end tell 

5 


end tell 


Adding a New Property List Item 

Listing 35-3 shows how to add a new key and value to a property list file. 
Open in Script Editor 

Listing 35-5 AppleScript: Adding a new key and value to a property list file 


1 tell application "System Events" 

2 tell property list items of property list file thePropertyListFilePath 

2 make new property list item at end with properties {kind:string, 
name:"newStringKey", value:"new string value"} 

4 end tell 

5 end tell 
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Working with XML 


The XML Suite of the System Events scripting dictionary defines several classes that make it quick and easy 
to read and parse XML data. The XML file class represents any text file containing structured XML like the 
example data shown in Listing 36-1. 


Listing 36-1 XML: Example XML data 


1 <books> 

2 <book country="US"> 

3 <name>The Secret Lives of Cats</name> 
4 <publisher>Feline Press</publisher> 
5 </book> 

6 </books> 


At the top level, an XML file contains an XML data object that’s comprised of nested XML element objects. 
Each XML element object has a name and a value property, and may also contain XML attribute objects that 
define additional metadata. The example code in Listing 36-2 demonstrates how to access these classes to 
read and parse the contents of an XML file on the Desktop that contains the XML data from Listing 36-1. 


APPLESCRIPT 


Open in Script Editor 


Listing 36-2 AppleScript: Using System Events to parse an XML file 





Lt tell application "System Events" 

2 tell XML file "~/Desktop/Book Data.xml" 

3 tell XML element "books" 

4 set theBookElements to every XML element whose name = "book" 

5 --> {XML element 1 of XML element 1 of contents of XML file "Macintosh 
HD: Users: YourUserName:Desktop:Book Data.xml" of application "System Events"} 

6 

7 repeat with a from 1 to length of theBookElements 

8 set theCurrentBookElement to item a of theBookElements 

9 --> XML element 1 of XML element 1 of contents of XML file 
"Macintosh HD:Users: YourUserName:Desktop:Book Data.xml" of application "System 
Events" 

10 

AL tell theCurrentBookElement 

12 name of theCurrentBookElement 

13 --> "book" 

14 

15 name of every XML element 

16 --> {"name", "publisher"} 

17 

18 name of every XML attribute 

19 --> {"country"} 

20 

21 value of every XML attribute 

22 —-> {"US"} 

23 

24 set theBookName to value of XML element "name" 

25 --> "The Secret Lives of Cats" 

26 

27 set thePublisher to value of XML element "publisher" 

28 --> "Feline Press" 

29 end tell 

30 end repeat 

31 end tell 

32 end tell 


33 end tell 
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Automating the User Interface 


Unfortunately, not every Mac app has scripting support, and those that do may not always have scripting 
support for every task you want to automate. You can often work around such limitations, however, by writing 
a user interface script, commonly called a UI or GUI script. A user interface script simulates user interaction, 
such as mouse clicks and keystrokes, allowing the script to select menu items, push buttons, enter text into 
text fields, and more. 


Enabling User Interface Scripting 


User interface scripting relies upon the OS X accessibility frameworks that provide alternative methods of 
querying and controlling the interfaces of apps and the system. By default, accessibility control of apps is 
disabled. For security and privacy reasons, the user must manually enable it on an app-by-app (including 
script apps) basis. 
To enable accessibility control for an app 

1. Launch System Preferences and click Security & Privacy. 

2. Click the Privacy tab. 

3. Click Accessibility. 

4. Click the Add button (+). 

5. Choose an app and click Open. 

6. Select the checkbox to the left of the app. 


ee < HE Security & Privacy Q Search 


General FileVault —_ Firewall 


Location Services Allow the apps below to control your computer. 


B Contacts 
v % My UI Script 


fa Calendars 
/ Script Editor 


Reminders 


ss) 
iy} Twitter 
@ Accessibility 


& Diagnostics & Usage 


B Click the lock to prevent further changes. Advanced... 2? 


When running an app that requires accessibility control for the first time, the system prompts you to enable it. 
See Figure 37-1. 


Figure 37-1 An accessibility control prompt 





rN *My Ui Script* wouid iike to controi this computer 


i using accessibility features. 
Lee Grant access to this application in Security & Privacy 


preferences, located in System Preferences. 


< Open System Preferences 


Attempting to run an app that has not been given permission to use accessibility features results in an error. 
See Figure 37-2. 


Figure 37-2 An accessibility control error 





My UI Script is not allowed assistive access. 


System Events got an error: My UI Script is not 
WF allowed assistive access. (-1719) 





NOTE 
To run a user interface script in Script Editor, you must enable accessibility for Script Editor. 


Admin credentials are required to perform enable user interface scripting. 


Targeting an App 


User interface scripting terminology is found in the Processes Suite of the System Events scripting dictionary. 
This suite includes terminology for interacting with most types of user interface elements, including windows, 
buttons, checkboxes, menus, radio buttons, text fields, and more. In System Events, the process class 
represents a running app. Listing 37-1 shows how to target an app using this class. 


APPLESCRIPT 
Open in Script Editor 


Listing 37-1 AppleScript: Targeting an app for user interface scripting 


i tell application "System Events" 

2 tell process "Safari" 

3 -- Perform user interface scripting tasks 
4 end tell 

5 end tell 


To control the user interface of an app, you must first inspect the app and determine its element hierarchy. 
This can be done by querying the app. For example, Listing 37-2 asks Safari for a list of menus in the menu 
bar. 


APPLESCRIPT 
Open in Script Editor 


Listing 37-2 AppleScript: Querying an app for user interface element information 


1 tell application "System Events" 

2 tell process "Safari" 

3 name of every menu of menu bar 1 
4 end tell 

5 end tell 

6 


--> Result: {"Apple", "Safari", "File", "Edit", "View", "History", "Bookmarks", 


"Develop", "Window", "Help"} 


Accessibility Inspector (Figure 37-3) makes it even easier to identify user interface element information. This 
app is included with Xcode. To use it, open Xcode and select Xcode > Open Developer Tool > Accessibility 
Inspector. 


Figure 37-3 Accessibility Inspector 


@ @ Accessibility Inspector (Locked) 


V Hierarchy 
Y AXApplication 
v AXMenuBar 
 AXMenuBaritem 
 AXMenu 
AXMenultem 
¥ Attributes 
accessibilityRole AXMenultem 
accessibilityRoleDescription menu item 
accessibilityParent <AXMenu> 
isAccessibilityEnabled YES 
accessibilityTitle Pin Tab 
accessibilityHelp <nil> 
isAccessibilitySelected (W) YES 
accessibilityFrame x=-976.00 y=114.00 w 
¥ Actions 


accessibilityPerformCancel 
accessibilityPerformPress 


No Selection 


@ %F7 toggles element lock AW 4 > OL] 


Once you know how an element fits into an interface, you target it within that hierarchy. For example, button X 


of window Y of process Z. 


Clicking a Button 


Use the click command to click a button. Listing 37-3 clicks a button in the Safari toolbar to toggle the sidebar 
between open and closed. 


APPLESCRIPT 
Open in Script Editor 
Listing 37-3 AppleScript: Clicking a button 


1 tell application "System Events" 
2 tell process "Safari" 
3 tell toolbar of window 1 
4 click (first button where its accessibility description = "Sidebar") 
5 end tell 
6 end tell 

7 end tell 

8 --> Result: {button 1 of toolbar 1 of window "AppleScript: Graphic User Interface 


(GUI) Scripting" of application process "Safari" of application "System Events"} 


Choosing a Menu Item 


Menu items can have a fairly deep hierarchy within the interface of an app. A menu item generally resides 
within a menu, which resides within a menu bar. In scripting, they must be addressed as such. Listing 37-4 
selects the Pin Tab menu item in the Window menu of Safari. 


APPLESCRIPT 
Open in Script Editor 
Listing 37-4 AppleScript: Choosing a menu item 


tell application "System Events" 
tell process "Safari" 


set frontmost to true 


1 
2 
3 
4 click menu item "Pin Tab" of menu "Window" of menu bar 1 
5 end tell 

6 end tell 

7 --> Result: menu item "Pin Tab" of menu "Window" of menu bar item "Window" of menu 


bar 1 of application process "Safari" of application "System Events" 


NOTE 


Scripting the user interface of an app can be tedious and repetitious. To streamline the process, consider 
creating handlers to perform common functions. For example, Listing 37-5 shows a handler that can be used 
to choose any menu item of any menu in any running app. 


APPLESCRIPT 


Open in Script Editor 


Listing 37-5 AppleScript: A handler that chooses a menu item 


1 on chooseMenuItem(theAppName, theMenuName, theMenuItemName) 
2 try 
3 -- Bring the target app to the front 
4 tell application theAppName 
5) activate 
6 end tell 
7 
8 -- Target the app 
9 tell application "System Events" 
10 tell process theAppName 
11 
12 -- Target the menu bar 
dis} tell menu bar 1 
14 
15 -- Target the menu by name 
16 tell menu bar item theMenuName 
17 tell menu theMenuName 
18 
19 -- Click the menu item 
20 click menu item theMenuItemName 
21 end tell 
22 end tell 
23 end tell 
24 end tell 
25 end tell 
26 return true 
27 on error 
28 return false 
29 end try 


30 end chooseMenuItem 


Listing 37-6 calls the handler in Listing 37-5 to select the Pin Tab menu item in the Window menu of Safari. 
APPLESCRIPT 
Open in Script Editor 


Listing 37-6 AppleScript: Calling a handler to choose a menu item 


chooseMenuItem("Safari", "Window", "Pin Tab") 


Choosing a Submenu Item 


Some menus contain other menus. In these cases, it may be necessary to select a menu item in a submenu of 
a menu. Listing 37-7 demonstrates how this would be done by selecting a submenu item in Safari. 


APPLESCRIPT 
Open in Script Editor 
Listing 37-7 AppleScript: Selecting a submenu item 


i tell application "System Events" 

2 tell process "Safari" 

3 set frontmost to true 

4 click menu item "Email This Page" of menu of menu item "Share" of menu 


"File" of menu bar 1 


5 end tell 
6 end tell 
7 --> Result: {menu item "Email This Page" of menu "Share" of menu item "Share" of 


menu "File" of menu bar item "File" of menu bar 1 of application process "Safari 


of application "System Events"} 
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Manipulating Images 


Image Events is a scriptable background app in OS X that can be used to automate the manipulation of 
images without the need for a fully-featured image editor. You can use Image Events to: 

* Read image properties 

¢ Flip and rotate images 

* Crop and add padding to images 

« Resize images 


* Convert images from one type to another 


The Image Events app is located in /System/Library/CoreServices/. You can access its dictionary from the 
Library palette in Script Editor. See Opening a Scripting Dictionary. 


NOTE 


Image Events can read and save most standard image formats, including . bmp, . jpg, .png, .psd, and . tif. 
Image Events can read . pdf files, but cannot save them. 


The Image Events Workflow 
To manipulate an image with Image Events, a script typically performs the following sequential steps: 


1. Open the Image Events app. 

2. Open an image file. 

3. Access image properties or manipulate the image. 

4. Save the modified image as a new image file or overwriting the original image file. 


5. Close the image. 


Opening an Image 


An image must be opened before Image Events can interact with it. To open an image, use the open command 
and provide the image’s path, as shown in Listing 38-1. 


APPLESCRIPT 
Open in Script Editor 
Listing 38-1 AppleScript: Opening an image with Image Events 


-- Prompt for an image 


set theImageFile to choose file of type "public.image" with prompt "" 


-- Launch Image Events and open the image 
tell application "Image Events" 

launch 

open theImageFile 
end tell 
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--> Result: image "My Image.png" of application "Image Events" 


The result of the open command is an image object, the newly opened image. Since Image Events is a 
background app, opening an image produces no visible changes onscreen—you won’t actually see the 
opened image. 


NOTE 


When working with Image Events, use the Launch command to make sure it’s running rather than the 
activate command, which is reserved for apps with interfaces. 


Reading Image Properties 


Like all scriptable objects, images have attributes that define them, such as dimensions, color space, and 
resolution. The image class in the Image Events scripting dictionary contains a variety of properties for key 
attributes. Listing 38-2 shows how to access some of these properties. First, it retrieves a record of available 
properties for a selected image. Next, it retrieves some individual properties. 


APPLESCRIPT 
Open in Script Editor 


Listing 38-2 AppleScript: Retrieving properties from an image 


1 -- Prompt for an image 
2 set theImageFile to choose file of type "public.image" with prompt "" 
3 
4 -- Launch Image Events 
5 tell application "Image Events" 
6 launch 
7 
8 -- Open the image 
9 set theImage to open theImageFile 
10 
it -- Read the image's properties 
12 tell theImage 
13 properties 
14 --> {color space:RGB, image file:file "Macintosh 
HD: Users: YourUserName:Desktop:My Image.png" of application "Image Events", bit 
depth:millions of colors, dimensions:{293, 252}, location: folder "Macintosh 
HD:Users:YourUserName:Desktop:" of application "Image Events", embedded 
profile:profile "Thunderbolt Display" of image "My Image.png" of application 
"Image Events", file type:PNG, class:image, name:"My Image.png", resolution:{72.0, 
72.0}} 
15 
16 -- Read the image's resolution 
17 resolution 
18 --> {72.0, 72.0} 
19 
20 -- Read the image's type 
21 file type 
22 --> PNG 
23 
24 -- Read the name of the image's embedded profile 
25 name of embedded profile 
26 --> "Thunderbolt Display" 
27 end tell 


28 end tell 


Flipping an Image 


The flip command reverses the axis of an image. It has two options for the required parameter: horizontal 
for changing the axis of the image on a horizontal plane, and vertical for changing the axis of the image on a 
vertical plane. Listing 38-3 flips an image both horizontally and vertically. 


IMPORTANT 


The script in Listing 38-3 saves a chosen image as a new file with a prefix of temp-. If another file exists with 
this same name, it is overwritten. 


APPLESCRIPT 
Open in Script Editor 


Listing 38-3 AppleScript: Flipping an image 





1 -- Prompt for an image 
2 set theImageFile to choose file of type "public.image" with prompt "" 
3 
4 -- Locate an output folder 
5 set theOutputFolder to (path to desktop folder as string) 
6 
7 -- Launch Image Events 
8 tell application "Image Events" 
9 launch 
10 
11 -- Open the image 
IZ set theImage to open theImageFile 
13 tell theImage 
14 
15 -- Determine a save name for the image 
16 set theName to name 
17 set theSaveName to "temp-" & theName 
18 
19 -- Flip the image horizontally 
20 flip with horizontal 
21 
22 -- Flip the image vertically 
23 flip with vertical 
24 
25 -- Save the image to the output folder, using the save name 
26 save as file type in (theOutputFolder & theSaveName) 
27 
28 -- Close the image 
29 close 
30 end tell 


31 end tell 


Rotating an Image 


The rotate command rotates an image around its center point. To rotate an image clockwise, provide the 
command’s to angle parameter with an integer value between 1 to 359 (see Listing 38-4). To rotate an image 
counter-clockwise, provide a negative value, such as -90. 


IMPORTANT 


The script in Listing 38-4 saves a chosen image as a new file with a prefix of temp-. If another file exists with 
this same name, it is overwritten. 


APPLESCRIPT 

Open in Script Editor 

Listing 38-4 AppleScript: Rotating an image 
-- Prompt for an image 


set theImageFile to choose file of type "public.image" with prompt "" 


-- Locate an output folder 


set theOutputFolder to (path to desktop folder as string) 
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-- Launch Image Events 


8 tell application "Image Events" 


9 launch 
10 
11 -- Open the image 
12 set theImage to open theImageFile 
13 tell theImage 
14 
15 -- Determine a save name for the image 
16 set theName to name 
17 set theSaveName to "temp-" & theName 
18 
19 -- Rotate an image 45 degrees 
20 rotate to angle 45 
21 
22 -- Save the image to the output folder, using the save name 
23 save as file type in (theOutputFolder & theSaveName) 
24 
25 -- Close the image 
26 close 
27 end tell 


28 end tell 


Scaling an Image 


Scaling an image proportionally increases or decreases its dimensions. The scale command can resize 
images in one of two ways: 


* To scale an image by percentage, provide a decimal value for the by factor parameter. The value 1 is 
equivalent to 100%. The value .5 is 50%. The value 1.5 is 150% and so on. 
Use the following formula to determine the scaling factor: 
«percentage» * .@1 


* To scale an image to a specific size, provide an integer value for the to size parameter. This value 
indicates the maximum number of pixels for the resized image on its longest side. 


Scaling doesn’t change the resolution of an image. For example, a 72 dpi image that has been scaled to 50% 
of its original dimensions still has a resolution of 72 dpi. 


Listing 38-5 demonstrates how to resize an image. It can scale by percentage or pixels, depending on the 
value of a Boolean variable. 


IMPORTANT 


The script in Listing 38-5 saves a chosen image as a new file with a prefix of temp-. If another file exists with 
this same name, it is overwritten. 


APPLESCRIPT 

Open in Script Editor 

Listing 38-5 AppleScript: Scaling an image 
-- Prompt for an image 


set theImageFile to choose file of type "public.image" with prompt "" 


-- Locate an output folder 


set theOutputFolder to (path to desktop folder as string) 
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-- To scale by percentage, set this value to true. To scale to a specific size, set 
it to false. 


8 set scaleByPercentage to true 


10 -- Launch Image Events 





11 tell application "Image Events" 

12 launch 

13 

14 -- Open the image 

15 set theImage to open theImageFile 

16 tell theImage 

17 

18 -- Determine a save name for the image 

19 set theName to name 

20 set theSaveName to "temp-" & theName 

21 

22 -- Scale the image by 50% 

23 if scaleByPercentage = true then 

24 scale by factor 0.5 

25 

26 -- Scale the image to 100px on its longese side 
27 else 

28 scale to size 100 

29 end if 

30 

31 -- Save the image to the output folder, using the save name 
32 save as file type in (theOutputFolder & theSaveName) 
33 

34 -- Close the image 

35 close 

36 end tell 


37 end tell 


Cropping an Image 


Cropping an image removes pixels around all of its sides, centering the remaining area. The to dimensions 
required parameter takes a list of two integers: the new width and height, in pixels. In Listing 38-6, an image is 
cropped to 100 by 100 pixels. 


IMPORTANT 


The script in Listing 38-6 saves a chosen image as a new file with a prefix of temp-. If another file exists with 
this same name, it is overwritten. 


APPLESCRIPT 
Open in Script Editor 


Listing 38-6 AppleScript: Cropping an image 


1 -- Prompt for an image 
2 set theImageFile to choose file of type "public.image" with prompt "" 
3 
4 -- Locate an output folder 
5 set theOutputFolder to (path to desktop folder as string) 
6 
7 -- Launch Image Events 
8 tell application "Image Events" 
9 launch 
10 
at -- Open the image 
IZ set theImage to open theImageFile 
13 tell theImage 
14 
15 -- Determine a save name for the image 


16 set theName to name 


17 
18 
19 
20 
21 
22 
23 
24 
25) 
26 
27 
28 


set theSaveName to "temp-" & theName 


-- Crop the image to 100px by 100px 
crop to dimensions {100, 100} 


-- Save the image to the output folder, using the save name 


save as file type in (theOutputFolder & theSaveName) 


-- Close the image 
close 
end tell 
end tell 


Padding an Image 


Padding an image adds space around its sides. It’s essentially the reverse of cropping an image, although 
negative padding an image produces cropping. The to dimensions required parameter takes a list of two 
integers: the new width and height, in pixels. The optional with pad color parameter can be used to specify 
the color of the padding. In Listing 38-7, 20 pixels of padding is added around an image. 


IMPORTANT 


The script in Listing 38-7 saves a chosen image as a new file with a prefix of temp-. If another file exists with 
this same name, it is overwritten. 


APPLESCRIPT 


Open in Script Editor 


Listing 38-7 AppleScript: Padding an image 


ry ry ry 
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-- Prompt for an image 


set theImageFile to choose file of type "public.image" with prompt "" 


-- Prompt for a color 


set theColor to choose color 


-- Locate an output folder 


set theOutputFolder to (path to desktop folder as string) 


-- Launch Image Events 
tell application "Image Events" 


launch 


-- Open the image 
set theImage to open theImageFile 
tell theImage 


-- Determine a save name for the image 
set theName to name 


set theSaveName to "temp-" & theName 


-- Get the current dimensions of the image 


set {theWidth, theHeight} to dimensions 


-- Pad the image by 20 pixels on all sides 
pad to dimensions {theWidth + 20, theHeight + 20} with pad color theColor 


-- Save the image to the output folder, using the save name 


save as file type in (theOutputFolder & theSaveName) 


31 
32 
33 
34 


-- Close the image 
close 
end tell 
end tell 


NOTE 


Images containing transparency result in transparent padding, regardless of whether a color is specified. 


Converting an Image from One Type to Another 


To convert an image from one type to another, open it and save it in another format. Listing 38-8 saves a 
chosen image in . jpg, .psd, and . tif format. 


APPLESCRIPT 


Open in Script Editor 


Listing 38-8 AppleScript: Converting an image from one type to another 
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-- Prompt for an image 


set theImageFile to choose file of type "public.image" with prompt "" 


-- Locate an output folder 


set theOutputFolder to (path to desktop folder as string) 


-- Launch Image Events 
tell application "Image Events" 


launch 


-- Open the image 
set theImage to open theImageFile 


tell theImage 


-- Save the image as a .jpg 


save as JPEG in (theOutputFolder & "temp-conversion-output. jpg") 


-- Save the image as a .psd 


save as PSD in (theOutputFolder & "temp-conversion-output.psd") 


-- Save the image as a .tif 


save as TIFF in (theOutputFolder & "temp-conversion-output.tif") 


-- Close the image 
close 
end tell 
end tell 
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Calling Command-Line Tools 


In AppleScript, the do shell script command is used to execute command-line tools. This command is 
implemented by the Standard Additions scripting addition included with OS X. 


NOTE 


The Terminal app in /Applications/Utilities/ is scriptable and provides another way to execute 
command-line tools from scripts. 


Executing Commands 


The direct parameter of the do shell script command is a string containing the shell code you want to 
execute, as demonstrated in Listing 39-1, which simply lists a directory. 


APPLESCRIPT 
Open in Script Editor 
Listing 39-1 AppleScript: Executing a simple shell command that lists the contents of a directory 


do shell script "ls /Applications/" 
(x 

--> Result: 

"App Store.app 

Automator. app 

Calculator.app 

Calendar.app 


oO AN DU BP WYN 


*) 


Since the direct parameter of do shell script is a string, you can concatenate it with other strings at run 
time. Listing 39-2, for example, concatenates a shell command to a previously defined parameter value. 
APPLESCRIPT 

Open in Script Editor 


Listing 39-2 AppleScript: Concatenating a command with a value 


1 set theHostName to "www.apple.com" 


2 do shell script "ping -c1 " & theHostName 


Quoting Strings 

The shell uses space characters to separate parameters and gives special meaning to certain punctuation 
marks, such as $, (, ), and *. To ensure that strings are treated as expected—for example, spaces aren’t seen 
as delimiters—it’s best to wrap strings in quotes. This process is known as quoting. If your string contains 
quotes, they must also be escaped (preceded by a / character) so they are interpreted as part of the string. 
Listing 39-3 shows an example of an error occurring as a result of a parameter that contains a space. 


APPLESCRIPT 
Open in Script Editor 
Listing 39-3 AppleScript: An error resulting from a string containing a space 


1 set thePath to "/Library/Application Support/" 
2 do shell script "ls " & thePath 
3 --> Result: error "ls: /Library/Application: No such file or directory\rls: Support: 


No such file or directory" number 1 


The easiest way to quote a string is to use the quoted form property of the text class, as demonstrated in 
Listing 39-4. This property returns the string in a form that’s safe from further interpretation by the shell, 
regardless of its contents. 


APPLESCRIPT 
Open in Script Editor 


Listing 39-4 AppleScript: Quoting a string to prevent errors 


1 set thePath to quoted form of "/Library/Application Support/" 
2 --> Result: "'/Library/Application Support/'" 

3 do shell script "ls " & thePath 

4 (* 

5 --> Result: 

6 "App Store 

7 Apple 

8 

9 " 
10 *) 


More Information 


For more information about the do shell script command, see Commands Reference in AppleScript 
Language Guide and Technical Note TN2065. 
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Making a Systemwide Service 


In OS X, services let you access functionality in one app from within another app. An app that provides a 
service advertises the operations it can perform on a particular type of data. Services are triggered from the 
Application Name > Services menu, or from contextual menus that appear when you Control-click on text, 
files, and other kinds of data. When you’re manipulating a particular type of data, related services becomes 
available. For example, Mail provides a service that creates a new email from selected text. 


Making a Script Available as a Service 


A script can be made available as a service by embedding it in an Automator service workflow. 


To create a service workflow that runs a script 
1. Launch Automator, found in /Applications/. 
2. Create a new Automator document. 


3. When prompted, choose a document type of Service and click Choose. 


Choose a type for your document: 


log S 
|30e| am 





Workflow Application Print Plugin 
Folder Action Calendar Alarm Image Capture Dictation 
Plugin Command 


Fe Service 


Services are contextual workflows available throughout OS X. They accept 
text or files from the current application or the Finder. Services appear in the 
Services menu. 


Open an Existing Document... Close 


4. At the top of the Automator document, configure the service. 


Service receives selected text in any application 
Inputis entire selection $ Output replaces selected text 


If the service will process a specific type of data, such as text, files, or images, select the appropriate 
type. Otherwise, select “no input.” 


If the service will be available within the context of a specific app only, select the appropriate app. 
Otherwise, select “any application.” 


If the service will replace selected text with processed text, select the “Output replaces selected text” 
checkbox. 


5. Type run in the search field above the action library pane to filter the action library. 


A list of actions for running AppleScripts, JavaScripts, UNIX shell scripts, and more are displayed. 


GIS Variables 














y (jj) Library 
fa Calendar g@ Run JavaScript 
B Contacts 3 Run Self-Test 
x Developer BM Run Shell Script 
&& Files & Folders g# Run Web Service 
{B Fonts g@ Run Workflow 
@ Internet | 


6. Drag an action, such as Run AppleScript or Run JavaScript, to the workflow area. 


An interface for the action appears. 


Service receives selected text in any application 


Inputis entire selection $ ~ Output replaces selected text 





v @ Run AppleScript 


> ra 
on run {input, parameters} 
(* Your script goes here x*) 


return input 
end run 


Results Options 








7. Write the script code and add it to the action. If the action contains additional configuration options, 
adjust them as needed. 


For AppleScripts and JavaScripts, use the action’s run handler template to process input data when the 
service runs, such as text or files. For workflows that replace selected text with processed text, be sure 
your workflow results in a text value. See Example Service Workflow Scripts. 


Service receives selected _ text in any application 
Inputis entire selection c¢) Output replaces selected text 





v o Run AppleScript 


> 7 


on run {input, parameters} 
set input to changeCaseOfText(input as string, "upper") 
return input 

end run 


on changeCaseOfText(theText, theCaseToSwitchTo) 
if theCaseToSwitchTo contains "lower" then 
set theComparisonCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
set theSourceCharacters to "abcdefghijklmnopqrstuvwxyz" 
else if theCaseToSwitchTo contains "upper" then 
set theComparisonCharacters to "abcdefghijklmnopqrstuvwxyz" 
set theSourceCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
else 
return theText 
end if 
set theAlteredText to "" 
repeat with aCharacter in theText 
set theOffset to offset of aCharacter in theComparisonCharacters 
if theOffset is not 0 then 
set theAlteredText to (theAlteredText & character theOffset of 
theSourceCharacters) as string 
else 


set theAlteredText to (theAlteredText & aCharacter) as string 
end if 
end repeat 
return theAlteredText 
end changeCaseOfText 


Results Options 





8. Save the Automator document. 


When prompted, enter a name for the service. 


Save service as: Convert Selected Text to Uppercase| 


Example Service Workflow Scripts 


Listing 40-1 and Listing 40-2 provide example code that can be pasted into the Run AppleScript and Run 
JavaScript Automator actions to convert selected text to uppercase. 


APPLESCRIPT 
Open in Script Editor 


Listing 40-1 AppleScript: Example of an Automator service script that converts selected text to uppercase 





1 on run {input, parameters} 
2 set input to changeCaseOfText(input as string, "upper") 
3 return input 
4 end run 
5 
6 on changeCaseOfText(theText, theCaseToSwitchTo) 
7 if theCaseToSwitchTo contains "lower" then 
8 set theComparisonCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
9 set theSourceCharacters to "“abcdefghijklmnopqrstuvwxyz" 
10 else if theCaseToSwitchTo contains "upper" then 
11 set theComparisonCharacters to "abcdefghijklmnopqrstuvwxyz" 
12 set theSourceCharacters to "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 
13 else 
14 return theText 
15 end if 
16 set theAlteredText to "" 
17 repeat with aCharacter in theText 
18 set theOffset to offset of aCharacter in theComparisonCharacters 
19 if theOffset is not @ then 
20 set theAlteredText to (theAlteredText & character theOffset of 
theSourceCharacters) as string 
21 else 
22 set theAlteredText to (theAlteredText & aCharacter) as string 
23 end if 
24 end repeat 
25 return theAlteredText 


26 end changeCaseOfText 


JAVASCRIPT 
Open in Script Editor 


Listing 40-2 JavaScript: Example of an Automator service script that converts selected text to uppercase 


i function run(input, parameters) { 

2 var selectedText = input [@] 

3 return selectedText.toUpperCase( ) 
4 + 


Triggering Service Workflows 


Saved Automator service workflows automatically appear in services menus throughout the system at the 
appropriate time. For example, text processing workflows become available when you select text in an app. To 
run a service, select Application Name > Services > Service Workflow Name from the menu bar, or select 
Services > Service Workflow Name from a contextual menu. 
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Using the Systemwide Script Menu 


The OS X script menu provides quick access to your collection of scripts. Simply select a script in the menu at 
any time to run it instantly. Within the script menu, scripts can be organized into subfolders and by application. 
See Figure 41-1. 


Figure 41-1 The OS X script menu 


Eas © < 100%m@a SF Thu206PM Q 


Open Scripts Folder > 
Open Script Editor 


!™ ColorSync 
(Folder Actions 

(© Font Book 

(© Printing Scripts 

© Script Editor Scripts 
(© UI Element Scripts 
{© VoiceOver 


ViVi Viv Y. 


NOTE 


The script menu can run compiled scripts, as well as scripts saved as apps. It can also run UNIX shell scripts 
and Automator workflows. 


Enabling the Script Menu 


The script menu is disabled by default in OS X. 


To enable the script menu 
1. Launch Script Editor, located in /Applications/Utilities/. 
2. Select Script Editor > Preferences, or press Command-Comma (,), to open the preferences window. 
3. Click General in the toolbar. 
4. Enable the “Show Script menu in menu bar” checkbox. 


5. Choose whether application scripts—scripts that appear only when a corresponding app is in the front— 
should appear at the top or bottom of the script menu. 


ee General 


7 @ © 


General Editing Formatting History Plug-ins 


Default Script Editor: _/ Script Editor (2.8.1) 


Default Language: AppleScript (2.5) 


Default Target: Show “tell” application menu 
Dictionary Viewer: Show inherited items 


Script Menu: Show Script menu in menu bar 
Show Computer scripts 


Show application scripts: at top 


Oat bottom 











wile 


The script menu displays scripts in the ~/Library/Scripts/ folder of your user directory. To include scripts 
at the computer-level (in the /Library/Scripts/ folder), enable the “Show Computer scripts” checkbox. 


Adding User-Level Scripts to the Script Menu 
User-level scripts are scripts that only you can see and use. They aren’t available to other users on your Mac. 


To add user-level scripts to the script menu, save them into the ~/Library/Scripts/ folder of your user 
directory. For quick access to this folder, select Open Scripts Folder > Open User Scripts Folder from the 
script menu. When you do this, the folder is automatically created if it doesn’t already exist. 


Adding Computer-Level Scripts to the Script Menu 
Computer-level scripts are scripts that any user on your Mac can see and use. 


To add computer-level scripts to the script menu, save them into the /Library/Scripts/ folder on your Mac. 
For quick access to this folder, select Open Scripts Folder > Open Computer Scripts Folder from the script 
menu. When you do this, the folder is automatically created if it doesn’t already exist. 


Adding Application-Specific Scripts to the Script Menu 
Application-specific scripts are only visible in the script menu when a specific app is in the front. 


To add application-specific scripts to the script menu, save them into the 
~/Library/Scripts/Applications/«<ApplicationName» folder in your user directory or the 
/Library/Scripts/Applications/«ApplicationName» folder on your Mac. For quick access to this folder, 
bring the app to the front, then select Open Scripts Folder > Open «ApplicationName» Scripts Folder from the 
script menu. When you do this, a folder for the application is automatically created if it doesn’t already exist. 


Running Scripts in the Script Menu 


Select a script from the script menu to run it. If the script is an application, it launches and runs normally. If the 
script is a compiled script, a progress indicator appears in the menu bar. See Figure 41-2. 


Figure 41-2 Script menu progress 


ES $F Ow 101K = 
@ 


My Image Processor rx) 
Processing Images... (Proc... 





NOTE 


To reveal a script in the script menu, select it in the menu while pressing the Shift key. 


To open a script menu script in Script Editor, select it in the menu while pressing the Option key. 
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Using Dictation to Run Scripts 


Dictation commands is a powerful accessibility feature in OS X that lets you control your Mac using your voice. 
With dictation commands enabled, simply speak a command and watch it execute. The system comes with 
dozens of built-in dictation commands for opening apps, selecting menus, and more. You can extend the 
capabilities of dictation even further by creating your own custom commands using scripting and Automator. 


Enabling Dictation Commands 


You must enable dictation commands before you can use them. 


To enable dictation commands to run scripts 


1. Launch System Preferences and open the Dictation & Speech preference pane. 


ee < HE Dictation & Speech Q Search 


Text to Speech 


Use Dictation wherever you can type text. To start dictating, 
use the shortcut or select Start Dictation from the Edit menu. 


6 Dictation: Qon Off 


Use Enhanced Dictation 
Allows offline use and continuous dictation 
with live feedback. 


Display Audio v 


Language: English (United States) 


Shortcut: Press Fn (Function) Key Twice 


About Dictation and Privacy 2 


2. Click the On radio button to enable dictation. 
3. Click Use Enhanced Dictation. 


Enhanced dictation lets you perform dictation when your computer is offline, and is required to use 
dictation commands. Enabling this feature downloads some additional system content to your Mac. 


4. Open the Accessibility preference pane. 





ee < Accessibility Q Search 
I 1 Descriptions Dictation Commands allow you to edit text and interact with 
your computer by speaking to it. 
= Captions Dictation Commands... 
Hearing 
7 Use dictation commands even when you're not dictating text by 
& Audio saying the keyword phrase before the command name. 
Interacting Enable the dictation keyword phrase: 
Keyboard 
"> Mouse & Trackpad Play sound when command is recognized 


Mute audio output while dictating 


Show Accessibility status in menu bar 2 


5. In the list of accessibility features, click Dictation. 


6. Click Dictation Commands. 


ee < HH Accessibility Q Search 


= 
Pas Descriptions Dictation Commands allow you to edit text and interact with 
your computer by speaking to it. 
= Capione: Dictation Commands... 
Hearing 
“ Use dictation commands even when you're not dictating text by 
& Audio saying the keyword phrase before the command name. 
Interacting Enable the dictation keyword phrase: 
2 Keyboard 
"> Mouse & Trackpad Play sound when command is recognized 


Mute audio output while dictating 
Oo Switch Control 
& Dictation 


Show Accessibility status in menu bar % 


7. Select the“Enabled advanced commands” checkbox. 


Creating a Dictation Command Script 


Any script can serve as a dictation command. When the command is called, any code in the script’s run 
handler runs. 


To create a dictation command script 


1. Launch Script Editor and write a script that performs a task when run. 


2. Save the script in script format to the ~/Library/Speech/Speakable Items/ folder in your Home 
directory. 


If you want the script to be available to other users on your Mac, save it to the 
/Library/Speech/Speakable Items/ instead. 


3. Launch System Preferences and open the Accessibility preference pane. 
4. In the list of accessibility features, click Dictation. 


5. Click Dictation Commands. 


Q f arch 





Selection 

Select <phrase> 

Select all 

Select word 

Select previous word Select a command or click 
Select next word Add (+) to create a new command. 
Select sentence 

Select previous sentence 

Select next sentence 

Select paragraph 


+ 


Enable advanced commands Done 





6. Click + to adde a new dictation command. 
7. Enter a phrase to speak to invoke the script. 
8. Choose the application context for triggering the command, such as Any Application, Mail, or Safari. 


9. Choose Run Workflow > Other from the Perform pop-up menu. 


When | say: Send my weekly status report 


User F . —— 
a nm eee eee eet While usina: — Anv Application 
= 

Selection Perform: Run “Send Weekly Status R... 

Select <phrase> Save Workflow As... 

Select all 


Select word 

Select previous word 
Select next word 

Select sentence 

Select previous sentence 


+ — 


Enable advanced commands Done 


10. Click Done. 


Running a Dictation Command Script 


To run a dictation command —script or otherwise—press Fn key twice. When the dictation listener window 
(Figure 42-1) appears, say the name of the command you want to perform. 


Figure 42-1 Dictation listener window 


Done 


wl 


To make dictation even easier, select the “Enable the dictation keyword phrase” checkbox and enter a phrase 
in System Preferences > Accessibility > Dictation. Once enabled, you don’t need to press the Fn key twice 
anymore to trigger a command. Instead, just say the keyword phrase, followed by the name of the command. 
For example, if your keyword phrase is Computer, you might say “Computer, send my weekly status report.” 


Creating a Dictation Command Automator Workflow 
Automator can also be used to create dictation commands. 


To create a dictation command Automator workflow 


1. Launch Automator. 
2. Click Dictation Command in the template selection dialog. 


Choose a type for your document: 


SP wn, 


aS —_ 

, - “ — 
WFLOW = 
Workflow Application Service Print Plugin 





Folder Action Calendar Alarm Image Capture Dictation 
Plugin Command 
Ss Dictation Command 


Dictation Commands are workflows that are run when triggered by Dictation. 
They receive no input. 





Open an Existing Document... Close 





3. Add actions to the workflow. 


The Run AppleScript, Run JavaScript, and Run Shell Script actions can be used to initiate scripts from 
your workflow. 


4. At the top of the workflow, enter a dictation command and select the Command Enabled checkbox. 


eee # Untitled — Ecited ~ 
O A e. | i | > 


Library Media Record Step Stop Run 


Variabl 


me aa | 5 Bun Appleseriet © Command Enabled 
B Contacts 
% Developer Y # Run AppleScript 
& Files & Folders 
BG Fonts > HE 
@ Internet 
& mail 
@ Movies (* Your script goes here *) 
@ Music return input 
@ PDFs end run 
& Photos 
© Presentations 
@ System 
! Text Results Options 
XX Utilities 
(@ Most Used 
ti Recently Added 





on run {input, parameters} 





oe Run AppleScript 


This action runs the specified AppleScript. 
Input: Anything 
Result: Anything 
Version: 1.0.2 


Copyright: Copyright © 2004-2012 Apple Inc. All rights 
reserved. 











#y © 





im 








5. Save the workflow and name it. 


NOTE 


Automator dictation commands are automatically saved in the ~/Library/Speech/Speakable Items/ folder 
in your Home directory. 
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Objective-C to AppleScript Quick Translation Guide 


This appendix provides AppleScript equivalents for typical Objective-C features of a class. Below the table is a 


list of notes that correspond to the numbers in column 1. 


Note 


Objective-C 


@interface MyClass : NSObject { 
int myProperty; 
IBOutlet NSTextField +*myField; 
is 
IBOutlet @property (retain) NSButton 


*myButton; 


@end 


@implementation MyClass 


— (IBAction) myAction:(id) object f{ 


// No Arguments 
[object method]; 
// One Argument 
[object method: parameterName] ; 
// Multiple Argument 
[object 
methodWithArgument1: parameter1 


Argument2:parameter2] ; 


[object propertyName] ; 
object.propertyName; 


@end 


AppleScript 


script MyClass 
property parent: class "NSObject" 


property myProperty: 0 
property myField: missing value 


property myButton: missing value 


-- Handler with interleaved 
parameters 

on myAction: object 
-- or 
-- Handler with positional 
parameters 


on myAction_(object) 


-- No Arguments 
object's methodName() 
-- or 
methodName() of object 
-- or 
tell object to methodName() 
—- One Argument 
object's methodName: parameterName 
-- or 
methodName_(parameterName) of object 
-- or 
tell object to 
methodName: parameterName 
-- Multiple Arguments 
object's 
methodWithArgument1: parameter1 
Argument2: parameter2 


—- or 





methodwithArgument1_Argument2_(param 
eterl, parameter2) of object 

-- or 

tell object to 
methodWithArgument1:parameter1 


Argument2: parameter2 


object's propertyName() 
-- or 
propertyName() of object 
object's propertyName 
-- or 


propertyName of object 


end myAction_ 


end script 


1. An Objective-C class corresponds to an AppleScript script object. In AppleScript, inheritance is 
denoted using the parent property. 


2. An instance variable or @property in Objective-C corresponds to a property in AppleScript. 


AppleScript doesn’t require explicit tagging of Interface Builder outlet properties (IBOut Let). Interface 
Builder sees any property with a value of missing value as a potential outlet. 


3. Objective-C divides class definitions into an @interface section containing properties and an 
@implementation section containing method definitions. AppleScript has no such division. Properties 
and methods are all contained within the same script object. 


4. An Objective-C method definition corresponds to an AppleScript handler that uses either an interleaved- 
or positional-style for parameter placement. 

Interleaved parameters are preceded by colons and separated by spaces, similar to Objective-C syntax. 
See Handlers with Interleaved Parameters in AppleScript Language Guide. 

A positional parameter hander name is the Objective-C selector name, with colons changed to 
underscores. This handler name is followed by parentheses enclosing comma-separated parameters. 
See Handlers with Positional Parameters in AppleScript Language Guide. 

AppleScript doesn’t require explicit tagging of Interface Builder action methods (IBAction). Interface 
Builder sees any method with a single parameter as a potential action method. 

5. A method call in Objective-C corresponds to an AppleScript handler call that uses either interleaved- or 
positional-style parameters. Regardless of style, parameters must always be provided in the order the 
method definition specifies. 

AppleScript has three equivalent syntaxes for addressing object handlers and properties: object's 
method, method of object, and tell object to method. 

6. An Objective-C method with no parameters, such as a property or constant, can be called using an 
explicit accessor method call or more concise dot syntax. Similarly in AppleScript, a method with no 
parameters can be called using a handler call with empty parentheses, or as a property without the 
parentheses. 


7. In AppleScript, handlers and script objects are closed using the end syntax. 


Resolving Terminology Conflicts in AppleScriptObjC 


AppleScript distinguishes between reserved words, application identifiers, and user identifiers. Reserved 
words are terms defined by AppleScript itself. Application identifiers, also known as application keywords, are 
terms defined by an app’s scripting dictionary. User identifiers are variable or subroutine names defined by the 
script writer. 


Identifiers passed to AppleScriptObjC, in particular, Cocoa method names, must be user identifiers. If an 
identifier conflicts with a reserved word or an application identifier, you can force it to be considered a user 
identifier by escaping it—enclosing it in vertical bars. For example, the NSColor class has a set method for 
setting the current drawing color. However, set is a reserved AppleScript term for assigning variables. Calling 
the set method without escaping it would produce a syntax error. Listing 43-1 shows the correct usage. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-1 AppleScriptObjC: Escaping a method name that conflicts with a reserved word 


myColor's |set|() 

-- OR 

|set|() of myColor 

-—- OR 

tell myColor to |set|() 


wu B&B WN BR 


Similarly, NSWindow has a bounds property, but bounds is an application-defined term. Therefore, any 
references to this property must also be escaped. See Listing 43-2. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-2 AppleScriptObjC: Escaping a property name that conflicts with an application identifier 


get myWindow's |bounds| 
-- OR 

get |bounds| of myWindow 
-- OR 


wu BP WN 


tell myColor to get |bounds | 


When in doubt, add the vertical bars. If they’re unnecessary, they are merely redundant and harmless. 


Importing Frameworks 


To import a framework in AppleScript, use the use command, followed by the framework name. See Listing 43- 
3. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-3 AppleScriptObjC: Importing Foundation framework 


use framework "Foundation" 
set theString to "Hello World" 


1 
2 
3 
4 set theString to stringWithString_(theString) of NSString of current application 
5 set theString to (uppercaseString() of theString) as string 

6 


--> Result: "HELLO WORLD" 


Accessing Scripting Additions 


A normal AppleScript automatically loads and has access to terminology from scripting additions that are 
installed on the system. In AppleScriptObjC scripts, you must explicitly state that you want to use scripting 
addition terminology. Listing 43-4 shows how to do this. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-4 AppleScriptObjC: Using scripting additions 


1 use scripting additions 


2 display dialog "Hello World" as string 


Classes and Constants 


In AppleScriptObjC, Objective-C classes and constants are referred to in the context of the current 
application constant—a reference to the app that’s running the script. 


In this context, classes are referenced using the class specifier, followed by the class name, as shown in 
Listing 43-5. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-5 AppleScriptObjC: Referencing a class 


1 use framework "Foundation" 


2 class "NSView" of current application 


Constants are referenced without a preceding identifier. See Listing 43-6. 
APPLESCRIPT 

Open in Script Editor 

Listing 43-6 AppleScriptObjC: Referencing a constant 


use framework "Foundation" 


1 
2 
3 current application's NSCalibratedRGBColorSpace 
4 -- OR 

5 


NSCalibratedRGBColorSpace of current application 


Listing 43-7 demonstrates how to reference both Objective-C classes and constants. 
APPLESCRIPT 
Open in Script Editor 


Listing 43-7 AppleScriptObjC: Example of a script that references both classes and constants 


1 script MyView 

2 property parent : class "NSView" 

3 

4 on drawRect: rect 

5 set theWhiteColor to current application's class "NSColor"'s whiteColor() 

6 -- OR 

7 set theWhiteColor to whiteColor() of class "NSColor" of current application 
8 -- OR 

9 tell class "NSColor" of current application to set theWhiteColor to 


whiteColor() 


10 

11 theWhiteColor's colorUsingColorSpaceName: (current application's 
NSCalibratedRGBColorSpace) 

12 == OR 

13 colorUsingColorSpaceName_(NSCalibratedRGBColorSpace of current application) 
of theWhiteColor 

14 end drawRect: 

15 end script 





In places where current application is the current context, such as the top level of a script, current 
application may be shortened to my or me. In the case of class specifiers, it may be omitted entirely. See 
Listing 43-8. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-8 AppleScriptObjC: Referencing a classes and constants in the context of the current application 


use framework "Foundation" 


class "NSView" 


my NSCalibratedRGBColorSpace 
-- OR 


N OO UW FB WN BR 


NSCalibratedRGBColorSpace of me 


As a convenience technique to save typing, it’s good practice to define properties for classes at the top of your 
script. This way, you can refer to them by property name throughout your script. 


APPLESCRIPT 
Open in Script Editor 
Listing 43-9 AppleScriptObjC: Defining classes as properties 


script MyView 
property parent : class "NSView" 


property NSColor : class "NSColor" 


set theWhiteColor to NSColor's whiteColor() 
theWhiteColor's colorUsingColorSpaceName:NSCalibratedRGBColorSpace 


1 

2 

3 

4 

5 on drawRect: rect 
6 

7 

8 end drawRect: 
9 


end script 


Resources 


For additional information about AppleScriptObjC, see AppleScriptObjC Release Notes and the third-party 
book EveryDay AppleScriptObjC. 
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This table describes the changes to Mac Automation Scripting Guide. 
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New document that provides an introduction to using AppleScript and JavaScript 
to streamline workflows and increase productivity in OS X. 
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